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About  This  Report 


The  Secure  Coding  Standard  Described  in  This  Report 

The  CERT  Oracle  Secure  Coding  Standard  for  Java  is  the  result  of  a  collaboration  between  the 
CERT®  Program  at  the  Carnegie  Mellon  5’  Software  Engineering  Institute  and  Oracle.  It  is  being 
developed  as  a  community  effort  on  the  CERT  secure  coding  wiki  located  at 
www.securecoding.cert.org.  This  report  contains  a  subset  of  those  guidelines  that  deal  with  con¬ 
currency  and  may  undergo  further  revision  before  being  published  as  part  of  the  CERT  Oracle 
Secure  Coding  Standard  for  Java.  The  concurrency  guidelines  are  divided  into  the  following  cate¬ 
gories: 

•  visibility  and  atomicity  (VNA) 

•  locks  (LCK) 

.  thread  APIs  (THI) 

•  thread  pools  (TPS) 

•  thread-safety  miscellaneous  (TSM) 

We  welcome  your  feedback  about  these  guidelines.  To  comment  on  the  wiki,  simply  go  to  it  and 
sign  up  for  a  wiki  account. 

Guideline  Priorities 

Each  guideline  has  a  priority  assigned  using  a  metric  based  on  Failure  Mode,  Effects,  and  Critical¬ 
ity  Analysis  (FMECA)  [IEC  2006].  A  value  for  each  of  the  following  is  assigned  to  each  guide¬ 
line: 

•  severity  -  If  the  guideline  is  ignored,  how  serious  are  the  consequences? 

1  =  low  (denial-of-service  attack,  abnormal  termination) 

2  =  medium  (data  integrity  violation,  unintentional  infonnation  disclosure) 

3  =  high  (run  arbitrary  code,  privilege  escalation) 

•  likelihood  -  If  the  guideline  is  ignored  and  that  results  in  the  introduction  of  a  flaw,  how  like¬ 
ly  is  it  for  that  flaw  to  lead  to  an  exploitable  vulnerability? 

1  =  unlikely 

2  =  probable 

3  =  likely 

•  remediation  cost  —  How  expensive  is  it  to  comply  with  the  guideline? 

1  =  high  (manual  detection  and  correction) 

2  =  medium  (automatic  detection  and  manual  correction) 

3  =  low  (automatic  detection  and  correction) 

The  three  values  are  then  multiplied  for  each  guideline.  The  resulting  value,  which  will  be  be¬ 
tween  1  and  27,  provides  a  measure  that  can  be  used  to  prioritize  the  application  of  the  guidelines. 


CERT  and  Carnegie  Mellon  are  registered  in  the  U.S.  Patent  and  Trademark  Office  by  Carnegie  Mellon  Univer¬ 
sity. 
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Guidelines  with  a  priority  in  the  range  of  1-4  are  level-3  guidelines;  those  in  the  range  of  6-9  are 
level-2;  and  those  in  the  range  of  12-27  are  level- 1 .  As  a  result,  it  is  possible  to  claim  level- 1,  lev- 
el-2,  or  complete  compliance  (level-3)  with  a  standard  by  implementing  all  guidelines  in  a  level, 
as  shown  in  Figure  1 . 


High  severity, 
likely,  inexpensive 
to  repair  flaws 


LI  P12-P27 


Med  severity, 
probable,  med  cost 
to  repair  flaws 

L2  P6-P9 

L3P1-P4 

Low  severity, 
unlikely,  expensive 
to  repair  flaws 

Figure  1:  Guideline  Priorities 

This  metric  is  designed  primarily  for  remediation  projects.  New  development  efforts  are  expected 
to  conform  to  the  entire  standard. 
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Abstract 


An  essential  element  of  secure  coding  in  the  Java  programming  language  is  well-documented  and 
enforceable  coding  standards.  Coding  standards  encourage  programmers  to  follow  a  uniform  set 
of  guidelines  determined  by  the  requirements  of  the  project  and  organization,  rather  than  by  the 
programmer’s  familiarity  or  preference.  Once  established,  these  standards  can  be  used  as  a  metric 
to  evaluate  source  code  (using  manual  or  automated  processes). 

The  CERT  Oracle  Secure  Coding  Standard  for  Java  provides  guidelines  for  secure  coding  in  the 
Java  programming  language.  The  goal  of  these  guidelines  is  to  eliminate  insecure  coding  practices 
and  undefined  behaviors  that  can  lead  to  exploitable  vulnerabilities.  Applying  this  standard  will 
lead  to  higher  quality  systems  that  are  robust  and  more  resistant  to  attack. 

This  report  documents  the  portion  of  those  Java  guidelines  that  are  related  to  concurrency. 
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Introduction 


1  Introduction 


Memory  that  can  be  shared  between  threads  is  called  shared  memory  or  heap  memory.  The  term 
variable  as  used  in  this  technical  report  refers  to  both  fields  and  array  elements  [Gosling  2005]. 
Variables  that  are  shared  between  threads  are  referred  to  as  shared  variables.  All  instance  fields, 
static  fields,  and  array  elements  are  shared  variables  allocated  in  heap  memory.  Local  variables, 
fonnal  method  parameters,  and  exception-handler  parameters  are  never  shared  between  threads 
and  are  not  affected  by  the  memory  model. 


In  a  modern,  shared-memory,  multiprocessor  architecture,  each  processor  has  one  or  more  levels 
of  cache  that  are  periodically  reconciled  with  main  memory  as  shown  in  Figure  2. 


Core  1 

1  1 

Core  2 

1  1 

Core  3 

1  1 

Core  4 

MULTI-CORE  CHIP 

^J>, 

Main  memory 

Figure  2:  Modem,  Shared-Memory,  Multiprocessor  Architecture 


The  visibility  of  writes  to  shared  variables  can  be  problematic  because  the  value  of  a  shared  vari¬ 
able  may  be  cached  and  not  written  to  main  memory  immediately.  Consequently,  another  thread 
may  read  a  stale  value  of  the  variable. 


A  further  concern  is  that  concurrent  executions  of  code  are  typically  interleaved,  and  statements 
may  be  reordered  by  the  compiler  or  runtime  system  to  optimize  performance.  This  results  in  ex¬ 
ecution  orders  that  are  not  immediately  obvious  when  the  source  code  is  examined.  Failure  to  ac¬ 
count  for  possible  reorderings  is  a  common  source  of  data  races. 

Consider  the  following  example  in  which  a  and  b  are  (shared)  global  variables  or  instance  fields, 
but  rl  and  r2  are  local  variables  that  are  not  accessible  to  other  threads. 
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Initially,  let  a  =  0  and  b  =  0,  as  shown  in  Table  1 : 

Table  1:  Example  Thread  Assignment  #1 
Thread  1  Thread  2 

a  =  10;  b  =  20; 

rl  =  b;  r2  =  a; 

Because  the  two  assignments  in  Thread  1  (a  =  10;andrl  =  b ;)  are  unrelated,  the  compiler 
or  runtime  system  is  free  to  reorder  them.  Similarly  in  Thread  2,  the  statements  may  be  reordered 
freely.  Although  it  may  seem  counterintuitive,  the  Java  Memory  Model  (JMM)  allows  a  read  to 
see  the  value  of  a  write  that  occurs  later  in  the  execution  order. 


A  possible  execution  order  showing  actual  assignments  is  shown  in  Table  2. 
Table  2:  Example  #1  of  Assignments  in  Order  of  Execution 


Execution 

Order  (Time) 

Thread# 

Assignment 

Assigned  Value 

Notes 

1 

U 

a  =  10; 

10 

2 

b  =  20; 

20 

3 

fi 

rl  =  b; 

0 

Reads  initial  value  of  b,  that  is  0 

4 

r2  =  a; 

0 

Reads  initial  value  of  a,  that  is  0 

In  this  ordering,  rl  and  r2  read  the  original  values  of  variables  b  and  a,  respectively,  even 
though  they  are  expected  to  see  the  updated  values,  20  and  10.  Another  possible  execution  order 
showing  actual  assignments  is  shown  in  Table  3. 

Table  3:  Example  #2  of  Assignments  in  Order  of  Execution 


Execution 

Order  (Time) 

Thread# 

Assignment 

Assigned  Value 

Notes 

1 

U 

rl  =  b; 

20 

Reads  later  value  (in  Step  4)  of 

write,  that  is  20 

2 

r2  =  a; 

10 

Reads  later  value  (in  Step  3)  of 

write,  that  is  10 

3 

u 

a  =  10; 

10 

4 

b  =  20; 

20 

In  this  ordering,  rl  and  r2  read  the  values  of  a  and  b  written  from  Steps  3  and  4,  even  before  the 
statements  corresponding  to  these  steps  have  executed. 

Restricting  the  set  of  possible  reorderings  makes  it  easier  to  reason  about  the  correctness  of  the 
code. 

Even  if  statements  execute  in  the  order  of  their  appearance  in  a  thread,  caching  can  prevent  the 
latest  values  from  being  reflected  in  the  main  memory. 

The  Java  Language  Specification  defines  the  JMM  that  provides  certain  guarantees  to  the  Java 
programmer.  The  JMM  is  specified  in  terms  of  actions,  which  include  variable  reads  and  writes; 
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monitor  locks  and  unlocks;  and  thread  starts  and  joins.  The  JMM  defines  a  partial  ordering  called 
happens-before  on  all  actions  within  the  program.  To  guarantee  that  a  thread  executing  action  B 
can  see  the  results  of  action  A,  for  example,  a  happens-before  relationship  must  be  defined  such 
that  A  happens-before  B. 

According  to  Section  17.4.5  “Happens-before  Order”  of  the  Java  Language  Specification  [Gosl¬ 
ing  2005] 

1.  An  unlock  on  a  monitor  happens-before  every  subsequent  lock  on  that  monitor. 

2.  A  write  to  a  volatile  field  happens-before  eveiy  subsequent  read  of  that  field. 

3.  A  call  to  start()  on  a  thread  happens-before  any  actions  in  the  started  thread. 

4.  All  actions  in  a  thread  happens-before  any  other  thread  successfully  returns  from  a  join()  on 
that  thread. 

5.  The  default  initialization  of  any  object  happens-before  any  other  actions  (other  than  default- 
writes)  of  a  program. 

6.  A  thread  calling  interrupt  on  another  thread  happens-before  the  interrupted  thread  detects 
the  interrupt. 

7.  The  end  of  a  constructor  for  an  object  happens-before  the  start  of  the  finalizer  for  that  ob¬ 
ject. 

If  a  happens-before  relationship  does  not  exist  between  two  operations,  the  Java  Virtual  Machine 
(JVM)  is  free  to  reorder  them.  A  data  race  occurs  when  a  variable  is  written  to  by  at  least  one 
thread  and  read  by  at  least  another  thread,  and  the  reads  and  writes  are  not  ordered  by  a  happens- 
before  relationship.  A  correctly  synchronized  program  is  one  with  no  data  races.  The  JMM  guar¬ 
antees  sequential  consistency  for  correctly  synchronized  programs.  Sequential  consistency  means 
that  the  result  of  any  execution  is  the  same  as  if  the  reads  and  writes  by  all  threads  on  shared  data 
were  executed  in  some  sequential  order  and  the  operations  of  each  individual  thread  appear  in  this 
sequence  in  the  order  specified  by  its  program  [Tanenbaum  2002] — in  other  words 

1 .  Take  the  read  and  write  operations  performed  by  each  thread  and  put  them  in  the  order  in 
which  the  thread  executes  them  (thread  order). 

2.  Interleave  the  operations  in  some  way  allowed  by  the  happens-before  relationships  to  form 
an  execution  order. 

3.  Read  operations  must  return  the  most  recently  written  data  in  the  total  program  order  for  the 
execution  to  be  sequentially  consistent. 

If  the  program  is  sequentially  consistent,  all  threads  see  the  same  total  ordering  of  reads  and 
writes  of  shared  variables. 

The  actual  execution  order  of  instructions  and  memory  accesses  can  vary  as  long  as 

•  the  actions  of  the  thread  appear  to  that  thread  as  if  program  order  were  followed 

•  all  values  read  are  allowed  for  by  the  memory  model 

These  constraints  allow  the  programmer  to  understand  the  semantics  of  the  programs  they  write 
and  allow  compiler  writers  and  virtual  machine  implemented  to  perform  various  optimizations 
[Arnold  2006], 
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Several  concurrency  primitives  can  help  a  programmer  reason  about  the  semantics  of  multi¬ 
threaded  programs. 

1.1.1  The  volatile  Keyword 

Declaring  shared  variables  volatile  ensures  visibility  and  limits  reordering  of  accesses.  Volatile 
accesses  do  not  guarantee  the  atomicity  of  composite  operations  such  as  incrementing  a  variable. 
Consequently,  volatile  is  not  applicable  in  cases  where  the  atomicity  of  composite  operations 
must  be  guaranteed.  (See  guideline  “VNA02-J.  Ensure  that  compound  operations  on  shared  va¬ 
riables  are  atomic”  on  page  1 6  for  more  information.) 

Declaring  variables  volatile  establishes  a  happens-before  relationship  such  that  a  write  to  a  vola¬ 
tile  variable  is  always  seen  by  threads  performing  subsequent  reads  of  the  same  variable.  State¬ 
ments  that  occur  before  the  write  to  the  volatile  field  also  happens-before  any  reads  of  the  volatile 
field. 


Consider  two  threads  that  are  executing  some  statements  as  shown  in  Figure  3Figure  1. 


Thread  1  and  Thread  2  have  a  happens-before  relationship  such  that  Thread  2  does  not  start  before 
Thread  1  finishes. 

In  this  example,  statement  3  writes  to  a  volatile  variable,  and  statement  4  (in  Thread  2)  reads  the 
same  volatile  variable.  The  read  sees  the  most  recent  write  (to  the  same  variable  v)  from  statement 
3. 

Volatile  read  and  write  operations  cannot  be  reordered  with  respect  to  each  other  or  to  non¬ 
volatile  variables  accesses.  When  Thread  2  reads  the  volatile  variable,  it  sees  the  results  of  all  the 
writes  occurring  before  the  write  to  the  volatile  variable  in  Thread  1.  Because  of  the  relatively 
strong  guarantees  of  volatile  read  and  write  operations,  the  performance  overhead  is  almost  the 
same  as  that  of  synchronization. 


CMU/SEI-2010-TR-015  |  4 


Introduction 


In  the  previous  example,  there  is  no  guarantee  that  statements  1  and  2  will  be  executed  in  the  or¬ 
der  in  which  they  appear  in  the  program.  They  may  be  reordered  freely  by  the  compiler  because 
there  is  no  happens-before  relationship  between  these  two  statements. 


The  possible  reorderings  between  volatile  and  non-volatile  variables  are  summarized  in  Table  4. 
Load  and  store  operations  are  synonymous  to  read  and  write  operations,  respectively  [Lea  2008]. 

Table  4:  Possible  Reorderings  Between  Volatile  and  Non-Volatile  Variables 


Can  Reorder 

2nd  Operation 

1st  Operation 

Normal  Load 

Normal  Store 

Volatile  Load 

Volatile  Store 

Normal  load 

Yes 

Yes 

Yes 

No 

Normal  store 

Yes 

Yes 

Yes 

No 

Volatile  load 

No 

No 

No 

No 

Volatile  store 

Yes 

Yes 

No 

No 

1.1.2  Synchronization 

A  correctly  synchronized  program  is  one  whose  sequentially  consistent  executions  do  not  have 
any  data  races.  The  example  shown  below  uses  a  non-volatile  variable  x  and  a  volatile  variable  y 
and  is  not  correctly  synchronized. 

Table  5:  Example  Thread  Assignment  #2 


Thread  1 

Thread  2 

x=  1 

rl  =  y 

CM 

II 

r2  =  x 

The  two  sequentially  consistent  execution  orders  of  this  example  are  shown  in  Table  6  and  Table 
7. 

Table  6:  Execution  Order  #1 


Step  (Time) 

Thread# 

Statement 

Comment 

1 

b 

x=  1 

Write  to  non-volatile  variable 

2 

U 

< 

II 

N> 

Write  to  volatile  variable 

3 

h 

rl  =  y 

Read  of  volatile  variable 

4 

r2  =  x 

Read  of  non-volatile  variable 

Table  7;  Execution  Order  #2 


Step  (Time) 

Thread# 

Statement 

Comment 

1 

rl  =  y 

Read  of  volatile  variable 

2 

r2  =  x 

Read  of  non-volatile  variable 

3 

b 

x=  1 

Write  to  non-volatile  variable 

4 

U 

y  =  2 

Write  to  volatile  variable 

In  the  first  case,  a  happens-before  relationship  exists  between  actions  such  that  Steps  1  and  2  al¬ 
ways  occur  before  Steps  3  and  4.  However,  in  the  second  case,  no  happens-before  relationship 
exists  between  any  of  the  steps.  Consequently,  because  there  is  a  sequentially  consistent  execution 
that  has  no  happens-before  relationship,  this  example  contains  data  races. 
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Correct  visibility  guarantees  that  multiple  threads  accessing  shared  data  can  view  each  others’ 
results,  but  does  not  establish  the  order  of  when  each  thread  reads  or  writes  the  data.  Correct  syn¬ 
chronization  guarantees  that  threads  access  data  in  a  proper  order.  For  example,  the  code  shown 
below  ensures  that  there  is  only  one  sequentially  consistent  execution  order  that  performs  all  the 
actions  of  Thread  1  before  Thread  2. 

class  Assign  { 

public  synchronized  void  doSomething ( )  { 

//  Perform  Thread  1  actions 
x  =  1; 

Y  =  2; 

//  Perform  Thread  2  actions 
r  1  =  y  ; 
r2  =  x; 


When  using  synchronization,  there  is  no  need  to  declare  the  variable  y  volatile.  Synchronization 
involves  acquiring  a  lock,  performing  operations,  and  then  releasing  the  lock.  In  the  above  exam¬ 
ple,  the  doSomething  ( )  method  acquires  the  intrinsic  lock  of  the  class  object  (Assign).  This 
example  can  also  be  written  to  use  block  synchronization: 

class  Assign  { 

public  void  doSomething))  { 
synchronized  (this)  { 

//  Perform  Thread  1  actions 
x  =  1; 
y  =  2; 

//  Perform  Thread  2  actions 
rl  =  y; 
r2  =  x; 


} 

The  intrinsic  lock  used  in  both  examples  is  the  same. 

1.1.3  The  java  .util .  concurrent  Classes 
1.1. 3.1  Atomic  Classes 

Volatile  variables  are  useful  for  guaranteeing  visibility.  However,  they  are  insufficient  for  ensur¬ 
ing  atomicity.  Synchronization  fills  this  gap  but  incurs  overheads  of  context  switching  and  fre¬ 
quently  causes  lock  contention.  The  atomic  classes  of  package 

j  ava .  util .  concurrent .  atomic  provide  a  mechanism  for  reducing  contention  in  most  prac¬ 
tical  environments  while  at  the  same  time  ensuring  atomicity.  According  to  Goetz  and  colleagues 
[Goetz  2006] 

With  low  to  moderate  contention,  atomics  offer  better  scalability;  with  high  contention,  locks 
offer  better  contention  avoidance. 

The  atomic  classes  consist  of  implementations  that  exploit  the  design  of  modern  processors  by 
exposing  commonly  needed  functionality  to  the  programmer.  For  example,  the 
Atomiclnteger .  incrementAndGet  ( )  method  can  be  used  for  atomically  incrementing  a 
variable.  The  compare-and-swap  instruction(s)  provided  by  modem  processors  offer  more  fine¬ 
grained  control  and  can  be  used  directly  by  invoking  high-level  methods  such  as 
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j  ava  .  util .  concurrent .  atomic  .Atomic*  .  compareAndSet  ( )  where  the  asterisk  can 
be,  for  example,  an  Integer,  Long,  or  Boolean. 

1.1 .3.2  The  Executor  Framework 

The  j  ava .  util .  concurrent  package  provides  the  Executor  framework  that  offers  a  me¬ 
chanism  for  executing  tasks  concurrently.  A  task  is  a  logical  unit  of  work  encapsulated  by  a  class 
that  implements  Runnable  or  Callable.  The  Executor  framework  allows  task  submission  to 
be  decoupled  from  low-level  scheduling  and  thread  management  details.  It  provides  the  thread 
pool  mechanism  that  allows  a  system  to  degrade  gracefully  when  presented  with  more  requests 
than  the  system  can  handle  simultaneously. 

The  Executor  interface  is  the  core  interface  of  the  framework  and  is  extended  by  the 
ExecutorService  interface  that  provides  facilities  for  thread  pool  termination  and  obtaining 
return  values  of  tasks  (Futures).  The  ExecutorService  interface  is  further  extended  by  the 
ScheduledExecutorService  interface  that  provides  a  way  to  run  tasks  periodically  or  after 
some  delay.  The  Executors  class  provides  several  factory  and  utility  methods  that  are  preconfi¬ 
gured  with  commonly  used  configurations  of  Executor,  ExecutorService,  and  other  related 
interfaces.  For  example,  the  Executors  .  newFixedThreadPool  ( )  method  returns  a  fixed 
size  thread  pool  with  an  upper  limit  on  the  number  of  concurrently  executing  tasks  and  maintains 
an  unbounded  queue  for  holding  tasks  while  the  thread  pool  is  full.  The  base  (actual)  implementa¬ 
tion  of  the  thread  pool  is  provided  by  the  ThreadPoolExecutor  class.  This  class  can  be  instan¬ 
tiated  to  customize  the  task  execution  policy. 

The  j  ava .  util .  concurrent  utilities  are  preferred  over  traditional  synchronization  primitives 
such  as  synchronization  and  volatile  variables  because  the  j  ava .  util .  concurrent  utilities 
abstract  the  underlying  details,  provide  a  cleaner  and  less  error-prone  API,  are  easier  to  scale,  and 
can  be  enforced  using  policies. 

1.1. 3. 3  Explicit  Locking 

The  j  ava .  util .  concurrent  package  provides  the  ReentrantLock  class  that  has  additional 
features  not  provided  by  intrinsic  locks.  For  example,  the  ReentrantLock .  tryLock  ( )  me¬ 
thod  does  not  block  waiting  if  another  thread  is  already  holding  the  lock.  Acquiring  and  releasing 
a  ReentrantLock  has  the  same  semantics  as  acquiring  and  releasing  an  intrinsic  lock. 
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2  Visibility  and  Atomicity  (VNA)  Guidelines 


2.1  VNAOO-J.  Ensure  visibility  when  accessing  shared  primitive  variables 

Reading  a  shared  primitive  variable  in  one  thread  may  not  yield  the  value  of  the  most  recent  write 
to  the  variable  from  another  thread.  Consequently,  the  thread  may  observe  a  stale  value  of  the 
shared  variable.  To  ensure  the  visibility  of  the  most  recent  update,  either  the  variable  must  be  de¬ 
clared  volatile  or  the  reads  and  writes  must  be  synchronized. 

Declaring  a  shared  variable  volatile  guarantees  visibility  in  a  thread-safe  manner  only  when  both 
of  the  following  conditions  are  met: 

•  A  write  to  a  variable  does  not  depend  on  its  current  value. 

•  A  write  to  a  variable  does  not  depend  on  the  result  of  any  non-atomic  compound  operations 
involving  reads  and  writes  of  other  variables.  (For  more  information,  see  guideline  “VNA02- 
J.  Ensure  that  compound  operations  on  shared  variables  are  atomic”  on  page  16.) 

The  first  condition  can  be  relaxed  when  you  can  be  sure  that  only  one  thread  will  ever  update  the 
value  of  the  variable  [Goetz  2006].  Flowever,  code  that  relies  on  a  single-thread  confinement  is 
error-prone  and  difficult  to  maintain.  This  behavior  is  permissible  under  this  guideline  but  not 
recommended. 

Synchronizing  the  code  makes  it  easier  to  reason  about  its  behavior  and  is  frequently  more  secure 
than  simply  using  the  volatile  keyword.  However,  synchronization  has  a  somewhat  higher 
performance  overhead  and  can  result  in  thread  contention  and  deadlocks  when  used  excessively. 

Declaring  a  variable  volatile  or  correctly  synchronizing  the  code  guarantees  that  64-bit  primitive 
long  and  double  variables  are  accessed  atomically.  (For  more  information  on  sharing  those 
variables  among  multiple  threads,  see  guideline  “VNA05-J.  Ensure  atomicity  when  reading  and 
writing  64-bit  values”  on  page  33.) 

2.1.1  Noncompliant  Code  Example  (Non-Volatile  Flag) 


This  noncompliant  code  example  uses  a  shutdown  ( )  method  to  set  a  non-volatile  done  flag 
that  is  checked  in  the  run  ( )  method. 


final  class  ControlledStop  implements  Runnable  { 

private  boolean  done  =  false; 

@Override  public  void  run()  { 

while  ( ! done)  { 

try  { 

II  ... 

Thread. cur rentThread ( ) . sleep (1000) ; 

//  Do  something 

}  catch (InterruptedException  ie)  { 

Thread. currentThread ( )  . interrupt  ( ) ; 

} 

//  Reset  interrupted  status 
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} 

1 

public  void  shutdown ()  { 

done  =  true; 

| 

} 

If  one  thread  invokes  the  shutdown  ( )  method  to  set  the  flag,  a  second  thread  might  not  observe 
that  change.  Consequently,  the  second  thread  may  observe  that  done  is  still  false  and  incorrectly 
invoke  the  sleep  ( )  method.  A  compiler  is  allowed  to  optimize  the  code  if  it  determines  that  the 
value  of  done  is  never  modified  by  the  same  thread,  resulting  in  an  infinite  loop. 

2.1.2  Compliant  Solution  (volatile) 

In  this  compliant  solution,  the  done  flag  is  declared  volatile  to  ensure  that  writes  are  visible  to 
other  threads. 

final  class  ControlledStop  implements  Runnable  { 
private  volatile  boolean  done  =  false; 

@Override  public  void  run()  { 
while  ( ! done)  { 
try  { 

//  ... 

Thread. currentThread (). sleep (1000) ;  //  Do  something 
}  catch (InterruptedException  ie)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 


} 

public  void  shutdown ()  { 

done  =  true; 

1 

} 

2.1.3  Compliant  Solution  (java . util .  concurrent .  atomic .  AtomicBoolean) 

In  this  compliant  solution,  the  done  flag  is  declared  AtomicBoolean.  Atomic  types  also  guar¬ 
antee  that  writes  are  visible  to  other  threads. 

final  class  ControlledStop  implements  Runnable  { 

private  final  AtomicBoolean  done  =  new  AtomicBoolean (false) ; 

@Override  public  void  run()  { 
while  (!  done .  get  ()  )  { 

try  { 

II  ... 

Thread. currentThread (). sleep (1000) ;  //  Do  something 
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}  catch (InterruptedException  ie)  { 

Thread. currentThread (). interrupt () ;  //  Reset  interrupted  status 

} 

I 

I 

public  void  shutdown))  { 
done . set (true) ; 

| 

} 

2.1.4  Compliant  Solution  (synchronized) 

This  compliant  solution  uses  the  intrinsic  lock  of  the  Class  object  to  ensure  that  updates  become 
visible  to  other  threads. 

final  class  ControlledStop  implements  Runnable  { 
private  boolean  done  =  false; 

OOverride  public  void  run()  { 
while  (!isDone())  { 
try  { 

II  ... 

Thread. currentThread (). sleep (1000) ;  //  Do  something 
}  catch (InterruptedException  ie)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 


p 

public  synchronized  boolean  isDoneO  { 
return  done; 

} 

public  synchronized  void  shutdown ()  { 

done  =  true; 

} 

} 

While  this  is  an  acceptable  compliant  solution,  intrinsic  locks  cause  threads  to  block  and  may  in¬ 
troduce  contention.  On  the  other  hand,  volatile-qualified  shared  variables  do  not  block.  Excessive 
synchronization  can  also  make  the  program  prone  to  deadlock. 

Synchronization  is  a  more  secure  alternative  in  situations  where  the  volatile  keyword  or  a 
java  .  util .  concurrent .  atomic  .Atomic*  field  is  inappropriate,  such  as  if  a  variable’s 
new  value  depends  on  its  current  value.  For  more  information,  see  guideline  “VNA02-J.  Ensure 
that  compound  operations  on  shared  variables  are  atomic”  on  page  16. 
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Compliance  with  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that 
may  interact  with  untrusted  code”  on  page  4 1  can  reduce  the  likelihood  of  misuse  by  ensuring  that 
untrusted  callers  cannot  access  the  lock  object. 

2.1.5  Exceptions 

VNA00-EX1:  Class  objects  need  not  be  made  visible  because  they  are  created  by  the  virtual 
machine  and  their  initialization  always  precedes  any  subsequent  use. 

2.1.6  Risk  Assessment 


Failing  to  ensure  the  visibility  of  a  shared  primitive  variable  may  result  in  a  thread  observing  a 
stale  value  of  the  variable. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

VNA00-J 

medium 

probable 

medium 

P8 

L2 

2.1.7  References 

[Arnold  2006]  Section  14.10.3,  “The  Happens-Before  Relationship” 
[Bloch  2008]  Item  66:  “Synchronize  access  to  shared  mutable  data” 


[Gosling  2005]  Chapter  17,  Threads  and  Locks: 

Section  17.4.5,  “Happens-Before  Order” 

Section  17.4.3,  “Programs  and  Program  Order” 

Section  17.4.8,  “Executions  and  Causality  Requirements” 

[MITRE  2010]  CWE  ID  667,  “Insufficient  Locking” 

CWE  ID  413,  “Insufficient  Resource  Locking” 

CWE  ID  567,  “Unsynchronized  Access  to  Shared  Data” 
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2.2  VNA01-J.  Ensure  visibility  of  shared  references  to  immutable  objects 

A  common  misconception  is  that  shared  references  to  immutable  objects  are  visible  across  mul¬ 
tiple  threads  as  soon  as  they  are  updated.  For  example,  a  developer  can  mistakenly  believe  that  a 
class  containing  fields  referring  to  only  immutable  objects  is  immutable  and,  consequently, 
thread-safe. 

Section  14.10.2,  “Final  Fields  and  Security”  of  Java  Programming  Language,  Fourth  Edition 
states  [Arnold  2006] 

The  problem  is  that,  while  the  shared  object  is  immutable,  the  reference  used  to  access  the 
shared  object  is  itself  shared  and  often  mutable.  Consequently,  a  correctly  synchronized 
program  must  synchronize  access  to  that  shared  reference,  but  often  programs  do  not  do 
this,  because  programmers  do  not  recognize  the  need  to  do  it. 

References  to  both  immutable  and  mutable  objects  must  be  made  visible  to  all  the  threads.  Im¬ 
mutable  objects  can  be  shared  safely  among  multiple  threads.  However,  mutable  objects  may  not 
be  fully  constructed  when  their  references  are  made  visible.  Guideline  “TSM03-J.  Do  not  publish 
partially  initialized  objects”  on  page  162  describes  object  construction  and  visibility  issues  specif¬ 
ic  to  mutable  objects. 

2.2.1  Noncompliant  Code  Example 

This  noncompliant  code  example  consists  of  the  immutable  Helper  class: 

//  Immutable  Helper 
public  final  class  Helper  { 
private  final  int  n; 

public  Helper (int  n)  { 
this.n  =  n; 

} 

//  ... 

} 

and  a  mutable  Foo  class: 

final  class  Foo  { 

private  Helper  helper; 

public  Helper  getHelper()  { 
return  helper; 

} 

public  void  setHelper (int  num)  { 
helper  =  new  Helper (num) ; 

I 
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The  getHelper  ( )  method  publishes  the  mutable  helper  field.  Because  the  Helper  class  is 
immutable,  it  cannot  be  changed  after  it  is  initialized.  Furthermore,  because  Helper  is  immuta¬ 
ble,  it  is  always  constructed  properly  before  its  reference  is  made  visible  in  compliance  with 
guideline  “TSM03-J.  Do  not  publish  partially  initialized  objects”  on  page  162.  Unfortunately,  a 
separate  thread  could  observe  a  stale  reference  in  the  helper  field  of  the  Foo  class. 

2.2.2  Compliant  Solution  (Synchronization) 

This  compliant  solution  synchronizes  the  methods  of  the  Foo  class  to  ensure  that  no  thread  sees  a 
stale  Helper  reference. 

final  class  Foo  { 

private  Helper  helper; 

public  synchronized  Helper  getHelper ()  { 

return  helper; 

} 

public  synchronized  void  setHelper (int  num)  { 
helper  =  new  Helper (num) ; 

} 

} 

The  immutable  Helper  class  remains  unchanged. 

2.2.3  Compliant  Solution  (volatile) 

References  to  immutable  member  objects  can  be  made  visible  by  declaring  them  volatile. 

final  class  Foo  { 

private  volatile  Helper  helper; 

public  Helper  getHelper ()  { 

return  helper; 

I 

public  void  setHelper (int  num)  { 
helper  =  new  Helper (num); 

} 

} 

The  immutable  Helper  class  remains  unchanged. 
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2.2.4  Compliant  Solution  (java .  util .  concurrent  Utilities) 

This  compliant  solution  wraps  the  immutable  Helper  object  within  an  AtomicReference 
wrapper  that  can  be  updated  atomically. 

final  class  Foo  { 

private  final  AtomicReference<Helper>  helperRef  = 
new  AtomicReference<Helper> ( ) ; 

public  Helper  getHelperO  { 
return  helperRef . get ( ) ; 

f 

public  void  setHelper (int  num)  { 
helperRef . set (new  Helper (num) ) ; 

} 

The  immutable  Helper  class  remains  unchanged. 

2.2.5  Risk  Assessment 

The  assumption  that  classes  containing  immutable  objects  are  immutable  is  incorrect  and  can 
cause  serious  thread-safety  issues. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

VNA01-J 

low 

probable 

medium 

P4 

L3 

2.2.6  References 

[Arnold  2006]  Section  14.10.2,  “Final  Fields  and  Security” 

[Goetz  2006]  Section  3.4.2,  “Example:  Using  Volatile  to  Publish  Immutable  Objects” 
[Sun  2009b] 
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2.3  VNA02-J.  Ensure  that  compound  operations  on  shared  variables  are  atomic 

Compound  operations  are  operations  that  consist  of  more  than  one  discrete  operation.  Expressions 
that  include  postfix  or  prefix  increment  (++),  postfix  or  prefix  decrement  or  compound 
assignment  operators  always  result  in  compound  operations.  Compound  assignment  expressions 
use  operators  such  as  *=,  /=,  %=,  +=,  -=,  «=,  »=,  »>=,  A=,  and  =  [Gosling  2005]. 
Compound  operations  on  shared  variables  must  be  performed  atomically  to  prevent  data  races  and 
race  conditions. 

For  information  about  the  atomicity  of  a  grouping  of  calls  to  independently  atomic  methods  that 
belong  to  thread-safe  classes,  see  guideline  “VNA03-J.  Do  not  assume  that  a  group  of  calls  to  in¬ 
dependently  atomic  methods  is  atomic”  on  page  23. 

The  Java  Language  Specification  also  permits  reads  and  writes  of  64-bit  values  to  be  non-atomic. 
For  more  information,  see  guideline  “VNA05-J.  Ensure  atomicity  when  reading  and  writing  64- 
bit  values”  on  page  33. 

2.3.1  Noncompliant  Code  Example  (Logical  Negation) 

This  noncompliant  code  example  declares  a  shared  boolean  flag  variable  and  provides  a 
toggle  ( )  method  that  negates  the  current  value  of  flag. 

final  class  Flag  { 

private  boolean  flag  =  true; 

public  void  toggle ()  {  //  Unsafe 

flag  =  !flag; 

} 

public  boolean  getFlagO  {  //  Unsafe 
return  flag; 

} 

} 

Execution  of  this  code  may  result  in  a  data  race  because  the  value  of  flag  is  read,  negated,  and 
written  back. 
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Consider,  for  example,  two  threads  that  call  toggle  ( ) .  The  expected  effect  of  toggling  flag 
twice  is  that  it  is  restored  to  its  original  value.  However,  the  following  scenario  leaves  flag  in  the 
incorrect  state: 


Time 

flag= 

Thread 

Action 

1 

true 

U 

reads  the  current  value  of  flag,  true,  into  a  temporary  variable 

2 

true 

reads  the  current  value  of  flag,  (still)  true,  into  a  temporary  variable 

3 

true 

u 

toggles  the  temporary  variable  to  false 

4 

true 

toggles  the  temporary  variable  to  false 

5 

false 

fl 

writes  the  temporary  variable’s  value  to  flag 

6 

false 

writes  the  temporary  variable’s  value  to  flag 

As  a  result,  the  effect  of  the  call  by  C  is  not  reflected  in  flag;  the  program  behaves  as  if 
toggle  ( )  was  called  only  once,  not  twice. 

2.3.2  Noncompliant  Code  Example  (Bitwise  Negation) 

Similarly,  the  toggle  ( )  method  can  use  the  compound  assignment  operator  A=  to  negate  the 
current  value  of  flag. 

final  class  Flag  { 

private  boolean  flag  =  true; 

public  void  toggle ()  {  //  Unsafe 

flag  A=  true;  //  Same  as  flag  =  Iflag; 

} 

public  boolean  getFlagO  {  //  Unsafe 
return  flag; 

1 

} 

This  code  is  also  not  thread-safe.  A  data  race  exists  because  A=  is  a  non-atomic  compound  opera¬ 
tion. 

2.3.3  Noncompliant  Code  Example  (volatile) 

Declaring  flag  volatile  does  not  help  either: 

final  class  Flag  { 

private  volatile  boolean  flag  =  true; 

public  void  toggle ()  {  //  Unsafe 

flag  A=  true; 

| 

public  boolean  getFlagO  {  //  Safe 
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return  flag; 

| 

} 

This  code  remains  unsuitable  for  multithreaded  use  because  declaring  a  variable  volatile  does  not 
guarantee  the  atomicity  of  compound  operations  on  it. 

2.3.4  Compliant  Solution  (Synchronization) 

This  compliant  solution  declares  both  the  toggle  ( )  and  getFlag  ( )  methods  as  synchronized. 

final  class  Flag  { 

private  boolean  flag  =  true; 

public  synchronized  void  toggle  ()  { 

flag  A=  true;  //  Same  as  flag  =  Iflag; 

} 

public  synchronized  boolean  getFlag ()  { 
return  flag; 

} 

} 

This  guards  the  reads  and  writes  to  the  flag  field  with  a  lock  on  the  instance,  that  is,  this.  This 
compliant  solution  ensures  that  changes  are  visible  to  all  the  threads.  Now,  only  two  execution 
orders  are  possible,  one  of  which  is  shown  below. 


Time 

flag= 

Thread 

Action 

1 

true 

h 

reads  the  current  value  of  flag,  true,  into  a  temporary  variable 

2 

true 

fi 

toggles  the  temporary  variable  to  false 

3 

false 

fi 

writes  the  temporary  variable's  value  to  flag 

4 

false 

reads  the  current  value  of  flag,  false,  into  a  temporary  variable 

5 

false 

toggles  the  temporary  variable  to  true 

6 

true 

writes  the  temporary  variable's  value  to  flag 

The  second  execution  order  involves  the  same  operations,  but  ^  starts  and  finishes  before  t\. 

Compliance  with  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that 
may  interact  with  untrusted  code”  on  page  4 1  can  reduce  the  likelihood  of  misuse  by  ensuring  that 
untrusted  callers  cannot  access  the  lock  object. 

2.3.5  Compliant  Solution  (Volatile-Read,  Synchronized-Write) 

In  this  compliant  solution,  the  getFlag  ( )  method  is  not  synchronized,  and  flag  is  declared 
volatile.  This  solution  is  compliant  because  the  read  of  flag  in  the  getFlag  ( )  method  is  an 
atomic  operation  and  the  volatile  qualification  assures  visibility.  The  toggle  ( )  method  still  re¬ 
quires  synchronization  because  it  performs  a  non-atomic  operation. 
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final  class  Flag  { 

private  volatile  boolean  flag  =  true; 

public  synchronized  void  toggle ()  { 

flag  A  =  true;  //  Same  as  flag  =  !flag; 

I 

public  boolean  getFlagO  { 
return  flag; 

} 


This  approach  may  not  be  used  when  a  getter  method  performs  operations  other  than  just  return¬ 
ing  the  value  of  a  volatile  field  without  having  to  use  any  synchronization.  Unless  read  perfor¬ 
mance  is  critical,  this  technique  may  not  offer  significant  advantages  over  synchronization  [Goetz 
2006], 

Guideline  “VNA06-J.  Do  not  assume  that  declaring  an  object  reference  volatile  guarantees  visibil¬ 
ity  of  its  members”  on  page  35  also  addresses  the  volatile-read,  synchronized-write  pattern. 

2.3.6  Compliant  Solution  (Read-Write  Lock) 

This  compliant  solution  uses  a  read-write  lock  to  ensure  atomicity  and  visibility. 

final  class  Flag  { 

private  boolean  flag  =  true; 

private  final  ReadWriteLock  lock  =  new  ReentrantReadWriteLock ( ) ; 
private  final  Lock  readLock  =  lock. readLock 0 ; 
private  final  Lock  writeLock  =  lock. writeLock 0 ; 

public  synchronized  void  toggle  ()  { 

writeLock . lock  ( ) ; 
try  { 

flag  A  =  true;  //  Same  as  flag  =  !flag; 

}  finally  { 

writeLock . unlock ( ) ; 

1 

public  boolean  getFlagO  { 
readLock . lock ( ) ; 
try  { 

return  flag; 

}  finally  { 

readLock . unlock ( ) ; 

} 

| 

} 
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Read-write  locks  allow  shared  state  to  be  accessed  by  multiple  readers  or  a  single  writer  but  never 
both.  According  to  Goetz  [Goetz  2006] 

In  practice,  read-write  locks  can  improve  performance  for  frequently  accessed  read-mostlv 
data  structures  on  multiprocessor  systems;  under  other  conditions  they  perform  slightly 
worse  than  exclusive  locks  due  to  their  greater  complexity. 

Profiling  the  application  can  determine  the  suitability  of  read-write  locks. 

2.3.7  Compliant  Solution  (AtomicBoolean) 

This  compliant  solution  declares  flag  an  AtomicBoolean  type. 

import  j ava . util . concurrent . atomic .AtomicBoolean; 
final  class  Flag  { 

private  AtomicBoolean  flag  =  new  AtomicBoolean (true) ; 

public  void  toggle ()  { 
boolean  temp; 
do  { 

temp  =  flag.getO; 

}  while  (! flag . compareAndSet (temp,  itemp)); 

} 

public  AtomicBoolean  getFlagO  { 
return  flag; 

} 

} 

The  flag  variable  is  updated  using  the  compareAndSet  ( )  method  of  the  AtomicBoolean 
class.  All  updates  are  visible  to  other  threads. 

2.3.8  Noncompliant  Code  Example  (Addition  of  Primitives) 

In  this  noncompliant  code  example,  multiple  threads  can  invoke  the  setValues  ( )  method  to  set 
the  a  and  b  fields.  Because  this  class  does  not  test  for  integer  overflow,  a  user  of  the  Adder  class 
must  ensure  that  the  arguments  to  the  setValues  ( )  method  can  be  added  without  overflow. 

(For  more  information,  see  guideline  “INT00-J.  Perform  explicit  range  checking  to  ensure  integer 
operations  do  not  overflow.1”) 

final  class  Adder  { 
private  int  a; 
private  int  b; 

public  int  getSum()  { 
return  a  +  b; 

} 


This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 


CMU/SEI-2010-TR-015  |  20 


VNA02-J 


public  void  setValues (int  a,  int  b)  { 
this. a  =  a; 
this.b  =  b; 

'} 

} 

The  get  Sum  ( )  method  contains  a  race  condition.  For  example,  if  a  and  b  currently  have  the  val¬ 
ues  0  and  Integer .  MAX  VALUE,  respectively,  and  one  thread  calls  getSum  ( )  while  another 
calls  setValues  ( Integer ,MAX_VALUE,  0 ) ,  the  getSum  ( )  method  might  return  0  or 
Integer .  MAX_VALUE,  or  it  might  overflow  and  wrap.  Overflow  will  occur  when  the  first  thread 
reads  a  and  b  after  the  second  thread  has  set  the  value  of  a  to  Integer .  MAX_VALUE,  but  before 
it  has  set  the  value  of  b  to  0. 

Note  that  declaring  the  variables  volatile  does  not  resolve  the  issue  because  these  compound  oper¬ 
ations  involve  reads  and  writes  of  multiple  variables. 

2.3.9  Noncompliant  Code  Example  (Addition  of  Atomic  Integers) 

In  this  noncompliant  code  example,  a  and  b  are  replaced  with  atomic  integers. 

final  class  Adder  { 

private  final  Atomiclnteger  a  =  new  Atomiclnteger () ; 
private  final  Atomiclnteger  b  =  new  Atomiclnteger () ; 

public  int  getSum ()  { 

return  a.get()  +  b.get(); 

| 

public  void  setValues (int  a,  int  b)  { 
this . a . set (a) ; 
this . b . set (b) ; 

1 

} 

The  simple  replacement  of  the  two  int  fields  with  atomic  integers  in  this  example  does  not  elim¬ 
inate  the  race  condition  because  the  compound  operation  a .  get  ( )  +  b.get()  is  still  non- 
atomic. 

2.3.10  Compliant  Solution  (Addition) 

This  compliant  solution  synchronizes  the  setValues  ( )  and  getSum  ( )  methods  to  ensure  ato¬ 
micity. 

final  class  Adder  { 
private  int  a; 
private  int  b; 

public  synchronized  int  getSum ()  { 

return  a  +  b; 
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} 

public  synchronized  void  setValues (int  a,  int  b)  { 
this. a  =  a; 
this.b  =  b; 

} 

} 

Any  operations  within  the  synchronized  methods  are  now  atomic  with  respect  to  other  synchro¬ 
nized  methods  that  lock  on  that  object’s  monitor  (intrinsic  lock).  It  is  now  possible,  for  example, 
to  add  overflow  checking  to  the  synchronized  getSum  ( )  method  without  introducing  the  possi¬ 
bility  of  a  race  condition. 

2.3.11  Risk  Assessment 


If  operations  on  shared  variables  are  non-atomic,  unexpected  results  can  be  produced.  For  exam¬ 
ple,  information  can  be  disclosed  inadvertently  because  one  user  can  receive  information  about 
other  users. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

VNA02-J 

medium 

probable 

medium 

P8 

L2 
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2.4  VNA03-J.  Do  not  assume  that  a  group  of  calls  to  independently  atomic 
methods  is  atomic 

A  consistent  locking  policy  guarantees  that  multiple  threads  cannot  simultaneously  access  or 
modify  shared  data.  If  two  or  more  operations  need  to  be  performed  as  a  single  atomic  operation, 
a  consistent  locking  policy  must  be  implemented  using  either  intrinsic  synchronization  or 
j  ava .  util .  concurrent  utilities.  In  the  absence  of  such  a  policy,  the  code  is  susceptible  to 
race  conditions. 

Given  an  invariant  involving  multiple  objects,  a  programmer  may  incorrectly  assume  that  indivi¬ 
dually  atomic  operations  require  no  additional  locking.  Similarly,  programmers  may  incorrectly 
assume  that  using  a  thread-safe  Collection  does  not  require  explicit  synchronization  to  pre¬ 
serve  an  invariant  that  involves  the  collection’s  elements.  A  thread-safe  class  can  only  guarantee 
atomicity  of  its  individual  methods.  A  grouping  of  calls  to  such  methods  requires  additional  syn¬ 
chronization. 

Consider,  for  example,  a  scenario  where  the  standard  thread-safe  API  does  not  provide  a  single 
method  to  both  find  a  particular  person’s  record  in  a  Hashtable  and  update  the  corresponding 
payroll  information.  In  such  cases,  the  two  method  invocations  must  be  performed  atomically. 

Enumerations  and  iterators  also  require  explicit  synchronization  on  the  collection  object  (client- 
side  locking)  or  a  private  final  lock  object. 

Compound  operations  on  shared  variables  are  also  non-atomic.  For  more  information,  see  guide¬ 
line  “VNA02-J.  Ensure  that  compound  operations  on  shared  variables  are  atomic”  on  page  16. 

Guideline  “VNA04-J.  Ensure  that  calls  to  chained  methods  are  atomic”  on  page  29  describes  a 
specialized  case  of  this  guideline. 

2.4.1  Noncompliant  Code  Example  (AtomicRef  erence) 

This  noncompliant  code  example  wraps  Biglnteger  objects  within  thread-safe 

AtomicReference  objects. 

final  class  Adder  { 

private  final  AtomicReference<BigInteger>  first; 
private  final  AtomicReference<BigInteger>  second; 

public  Adder (Biglnteger  f,  Biglnteger  s)  { 

first  =  new  AtomicRef erence<BigInteger> (f ) ; 
second  =  new  AtomicReference<BigInteger> (s) ; 

} 

public  void  update (Biglnteger  f,  Biglnteger  s)  {  //  Unsafe 
first . set (f ) ; 
second. set (s) ; 

} 

public  Biglnteger  add()  {  //  Unsafe 
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return  first . get ( ) . add (second. get ( ) ) ; 

} 

} 

AtomicReference  is  an  object  reference  that  can  be  updated  atomically.  However,  operations 
that  combine  more  than  one  atomic  reference  are  non-atomic.  In  this  noncomp liant  code  example, 
one  thread  may  call  update  ( )  while  a  second  thread  may  call  add  ( ) .  This  might  cause  the 
add  ( )  method  to  add  the  new  value  of  first  to  the  old  value  of  second,  yielding  an  erroneous 
result. 

2.4.2  Compliant  Solution  (Method  Synchronization) 

This  compliant  solution  declares  the  update  ( )  and  add  ( )  methods  synchronized  to  guarantee 
atomicity. 

final  class  Adder  { 

II  ... 

public  synchronized  void  update (Biglnteger  f,  Biglnteger  s) { 
first . set (f ) ; 
second. set (s) ; 

} 

public  synchronized  Biglnteger  add()  { 
return  first . get ( ) . add (second. get ( ) ) ; 

} 

} 

2.4.3  Noncompliant  Code  Example  (synchronizedList) 

This  noncompliant  code  example  uses  a  j  ava .  util .  ArrayList<E>  collection,  which  is  not 
thread-safe.  However,  Collections  .  synchronizedList  is  used  as  a  synchronization  wrap¬ 
per  for  ArrayList.  An  array,  rather  than  an  iterator,  is  used  to  iterate  over  ArrayList  to  avoid 
a  ConcurrentModif icationException. 

final  class  IPHolder  { 

private  final  List<InetAddress>  ips  = 

Collections . synchronizedList (new  ArrayList<InetAddress> ( ) ) ; 

public  void  addAndPrintIPAddresses (InetAddress  address)  { 
ips . add (address) ; 

InetAddress [ ]  addressCopy  =  (InetAddress [] )  ips . toArray (new  InetAddress [0] ) ; 

//  Iterate  through  array  addressCopy  . . . 

} 

} 

Individually,  the  add  ( )  and  toArray  ( )  collection  methods  are  atomic.  However,  when  they  are 
called  in  succession  (for  example,  in  the  addAndPrintIPAddresses  ( )  method),  there  are  no 
guarantees  that  the  combined  operation  is  atomic.  A  race  condition  exists  in  the 
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addAndPrintIPAddresses  ( )  method  that  allows  one  thread  to  add  to  the  list  and  a  second 
thread  to  race  in  and  modify  the  list  before  the  first  thread  completes.  Consequently,  the 
addressCopy  array  may  contain  more  IP  addresses  than  expected. 

2.4.4  Compliant  Solution  (Synchronized  Block) 

The  race  condition  can  be  eliminated  by  synchronizing  on  the  underlying  list’s  lock.  This  com¬ 
pliant  solution  encapsulates  all  references  to  the  array  list  within  synchronized  blocks. 

final  class  IPHolder  { 

private  final  List<InetAddress>  ips  = 

Collections . synchronizedList (new  ArrayList<InetAddress> ( ) ) ; 

public  void  addAndPrintIPAddresses (InetAddress  address)  { 
synchronized  (ips)  { 
ips . add (address) ; 

InetAddress [ ]  addressCopy  =  (InetAddress [] )  ips . toArray (new  InetAddress [0] ) ; 

//  Iterate  through  array  addressCopy  . . . 

} 

} 

} 


This  technique  is  also  called  client-side  locking  [Goetz  2006]  because  the  class  holds  a  lock  on  an 
object  that  might  be  accessible  to  other  classes.  Client-side  locking  is  not  always  an  appropriate 
strategy;  see  guideline  “LCK1 1-J.  Avoid  client-side  locking  when  using  classes  that  do  not  com¬ 
mit  to  their  locking  strategy”  on  page  86  for  more  information. 

This  code  does  not  violate  guideline  “LCK04-J.  Do  not  synchronize  on  a  collection  view  if  the 
backing  collection  is  accessible”  on  page  57  because,  while  it  does  synchronize  on  a  collection 
view  (the  synchronizedList),  the  backing  collection  is  inaccessible  and  therefore  cannot  be 
modified  by  any  code. 

2.4.5  Noncompliant  Code  Example  (synchronizedMap) 

This  noncompliant  code  example  defines  the  KeyedCounter  class  that  is  not  thread-safe.  Al¬ 
though  the  HashMap  is  wrapped  in  a  synchronizedMap,  the  overall  increment  operation  is 
non-atomic  [Lee  2009]. 

final  class  KeyedCounter  { 

private  final  Map<String,  Integer>  map  = 

Collections . synchronizedMap (new  HashMap<String,  Integer>()); 

public  void  increment (String  key)  { 

Integer  old  =  map . get (key) ; 

int  oldValue  =  (old  ==  null)  ?  0  :  old. intValue ( ) ; 
if  (oldValue  ==  Integer .MAX_VALUE)  { 

throw  new  ArithmeticException ( "Out  of  range"); 

} 

map.put(key,  oldValue  +  1) ; 
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} 

public  Integer  getCount (String  key)  { 
return  map . get (key) ; 

} 

} 

2.4.6  Compliant  Solution  (Synchronization) 

To  ensure  atomicity,  this  compliant  solution  uses  an  internal  private  lock  object  to  synchronize  the 
statements  of  the  increment  ( )  and  getCount  ( )  methods. 

final  class  KeyedCounter  { 

private  final  MapkString,  Integer>  map  =  new  HashMapkString,  Integer>(); 
private  final  Object  lock  =  new  Object!); 

public  void  increment (String  key)  { 
synchronized  (lock)  { 

Integer  old  =  map . get (key) ; 

int  oldValue  =  (old  ==  null)  ?  0  :  old. intValue ( ) ; 
if  (oldValue  ==  Integer ,MAX_VALUE)  { 

throw  new  ArithmeticException ( "Out  of  range"); 

} 

map.put(key,  oldValue  +  1) ; 


public  Integer  getCount (String  key)  { 
synchronized  (lock)  { 
return  map . get (key) ; 

} 

} 

} 

This  compliant  solution  does  not  use  Collections  .  synchronizedMap  ( )  because  locking 
on  the  unsynchronized  map  provides  sufficient  thread-safety  for  this  application.  Guideline 
“LCK04-J.  Do  not  synchronize  on  a  collection  view  if  the  backing  collection  is  accessible”  on 
page  57  provides  more  infonnation  about  synchronizing  on  synchronizedMap  objects. 

2.4.7  Compliant  Solution  (ConcurrentHashMap) 

The  previous  compliant  solution  is  safe  for  multithreaded  use,  but  it  does  not  scale  well  because 
of  excessive  synchronization,  which  can  lead  to  contention  and  deadlock. 

The  ConcurrentHashMap  class  used  in  this  compliant  solution  provides  several  utility  methods 
for  performing  atomic  operations  and  is  often  a  good  choice  for  algorithms  that  must  scale  [Lee 
2009], 

final  class  KeyedCounter  { 

private  final  ConcurrentMapkString,  AtomicInteger>  map  = 
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new  ConcurrentHashMap<String,  AtomicInteger> ( ) ; 

public  void  increment (String  key)  { 

Atomiclnteger  value  =  new  Atomiclnteger () ; 

Atomiclnteger  old  =  map .putlfAbsent (key,  value); 

if  (old  !=  null)  { 
value  =  old; 

} 

if  ( value. get ()  ==  Integer .MAX_VALUE)  { 

throw  new  ArithmeticException ( "Out  of  range"); 

} 

value . incrementAndGet () ;  //  Increment  the  value  atomically 

} 

public  Integer  getCount (String  key)  { 

Atomiclnteger  value  =  map . get (key) ; 
return  (value  ==  null)  ?  null  :  value. get  (); 

} 

//  Other  accessors  . . . 


According  to  Section  5.2.1.,  “ConcurrentHashMap”  of  the  work  of  Goetz  and  colleagues  [Goetz 
2006] 

ConcurrentHashMap,  along  with  the  other  concurrent  collections,  further  improve  on  the 
synchronized  collection  classes  by  providing  iterators  that  do  not  throw  Concur  rentMo- 
dificationException,  as  a  result  eliminating  the  need  to  lock  the  collection  during  ite¬ 
ration.  The  iterators  returned  by  ConcurrentHashMap  are  weakly  consistent  instead  of 
fail-fast.  A  weakly  consistent  iterator  can  tolerate  concurrent  modification,  traverses  ele¬ 
ments  as  they  existed  when  the  iterator  was  constructed,  and  may  (but  is  not  guaranteed  to) 
reflect  modifications  to  the  collection  after  the  construction  of  the  iterator. 

Note  that  methods  such  as  ConcurrentHashMap .  size  ( )  and  ConcurrentHash¬ 
Map  .  isEmpty  ( )  are  allowed  to  return  an  approximate  result  for  performance  reasons.  Code 
should  not  rely  on  these  return  values  for  deriving  exact  results. 
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2.4.8  Risk  Assessment 


Failing  to  ensure  the  atomicity  of  two  or  more  operations  that  need  to  be  performed  as  a  single 
atomic  operation  can  result  in  race  conditions  in  multithreaded  applications. 
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P4 
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2.5  VNA04-J.  Ensure  that  calls  to  chained  methods  are  atomic 

Method  chaining  is  a  convenience  mechanism  that  allows  multiple  method  invocations  on  the 
same  object  to  occur  in  a  single  statement.  A  method-chaining  implementation  consists  of  a  series 
of  methods  that  return  the  this  reference.  This  implementation  allows  a  caller  to  invoke  methods 
in  a  chain  by  performing  the  next  method  invocation  on  the  return  value  of  the  previous  method  in 
the  chain. 

While  the  methods  used  in  method  chaining  can  be  atomic,  the  chain  they  comprise  is  inherently 
non-atomic.  Consequently,  methods  that  are  involved  in  method  chaining  should  not  be  invoked 
concurrently  unless  the  caller  provides  sufficient  locking  as  illustrated  in  guideline  “VNA03-J.  Do 
not  assume  that  a  group  of  calls  to  independently  atomic  methods  is  atomic”  on  page  23. 

2.5.1  Noncompliant  Code  Example 

Method  chaining  is  a  useful  design  pattern  for  building  an  object  and  setting  its  optional  fields.  A 
class  that  supports  method  chaining  provides  several  setter  methods  that  each  return  the  this 
reference.  However,  if  accessed  concurrently,  a  thread  may  observe  shared  fields  to  contain  in¬ 
consistent  values.  This  noncompliant  code  example  shows  the  JavaBeans  pattern,  which  is  not 
thread-safe. 

final  class  USCurrency  { 

//  Change  requested,  denomination  (optional  fields) 

private  int  quarters  =  0; 

private  int  dimes  =  0; 

private  int  nickels  =  0; 

private  int  pennies  =  0; 

public  USCurrency ()  {} 

//  Setter  methods 

public  USCurrency  setQuarters  (int  quantity)  { 
quarters  =  quantity; 
return  this; 

.1 

public  USCurrency  setDimes  (int  quantity)  { 
dimes  =  quantity; 
return  this; 

} 

public  USCurrency  setNickels (int  quantity)  { 
nickels  =  quantity; 
return  this; 

i 

public  USCurrency  setPennies (int  quantity)  { 
pennies  =  quantity; 
return  this; 
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//  Client  code: 

private  final  USCurrency  currency  =  new  USCurrency () ; 

II  ... 

new  Thread (new  Runnable ()  { 

©Override  public  void  run()  { 

currency. setQuarters (1) . setDimes (1) ; 

1 

} )  . start  ( ) ; 

new  Thread (new  Runnable ()  { 

©Override  public  void  run()  { 

currency. setQuarters (2 ) . setDimes (2 ) ; 

I 

})  .start  ()  ; 


The  JavaBeans  pattern  uses  a  no-argument  constructor  and  a  series  of  parallel  setter  methods  to 
build  an  object.  This  pattern  is  not  thread-safe  and  can  lead  to  inconsistent  object  state  if  the  ob¬ 
ject  is  modified  concurrently.  In  this  noncomp liant  code  example,  the  client  constructs  a 
USCurrency  object  and  starts  two  threads  that  use  method  chaining  to  set  the  optional  values  of 
the  USCurrency  object.  This  example  code  might  result  in  the  USCurrency  instance  being  left 
in  an  inconsistent  state,  for  example,  with  two  quarters  and  one  dime,  or  one  quarter  and  two  di¬ 
mes. 

2.5.2  Compliant  Solution 

This  compliant  solution  uses  a  variant  of  the  Builder  pattern  [Gamma  1995]  suggested  by  Bloch 
[Bloch  2008]  to  ensure  the  thread-safety  and  atomicity  of  object  creation. 

final  class  USCurrency  { 

private  final  int  quarters; 
private  final  int  dimes; 
private  final  int  nickels; 
private  final  int  pennies; 

public  USCurrency (Builder  builder)  { 
this . quarters  =  builder . quarters; 
this. dimes  =  builder . dimes; 
this. nickels  =  builder . nickels; 
this. pennies  =  builder .pennies; 

} 

//  Static  class  member 
public  static  class  Builder  { 
private  int  quarters  =  0; 
private  int  dimes  =  0; 
private  int  nickels  =  0; 
private  int  pennies  =  0; 
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public  static  Builder  newlnstance ( )  { 
return  new  Builder  (); 

} 


private  Builder ()  {} 


//  Setter  methods 

public  Builder  setQuarters (int  quantity)  { 
this . quarters  =  quantity; 
return  this; 

1 

public  Builder  setDimes (int  quantity)  { 
this. dimes  =  quantity; 
return  this; 


public  Builder  setNickels (int  quantity)  { 
this. nickels  =  quantity; 
return  this; 


public  Builder  setPennies (int  quantity)  { 
this. pennies  =  quantity; 
return  this; 

I 


public  USCurrency  build ()  { 
return  new  USCurrency (this ) ; 


} 


//  Client  code: 

private  volatile  USCurrency  currency; 

II  ... 

new  Thread (new  Runnable ()  { 

©Override  public  void  run()  { 

currency  =  USCurrency .Builder . newlnstance ( ) . setQuarters (1 ) . setDimes (1 ) .build ( ) ; 

1 

})  .start  ()  ; 

new  Thread (new  Runnable ()  { 

©Override  public  void  run()  { 

currency  =  USCurrency .Builder . newlnstance ( )  . setQuarters  (2 )  . setDimes (2 )  .build ( ) ; 

} 

})  .start  ()  ; 


The  Builder .  newlnstance  ( )  factory  method  is  called  with  any  required  arguments  to  obtain 
a  Builder  instance.  The  optional  parameters  are  set  using  the  setter  methods  of  the  builder.  The 


CMU/SEI-2010-TR-015  |  31 


VNA04-J 


object  construction  concludes  with  the  invocation  of  the  build  ( )  method.  This  pattern  makes 
the  USCurrency  class  immutable  and,  consequently,  thread-safe. 

Note  that  the  currency  field  cannot  be  declared  final  because  it  is  assigned  a  new  immutable 
object.  It  is,  however,  declared  volatile  in  compliance  with  guideline  “VNA01-J.  Ensure  visibility 
of  shared  references  to  immutable  objects”  on  page  13. 

If  input  needs  to  be  validated,  ensure  that  the  values  are  defensively  copied  prior  to  validation  (see 
guideline  “FIOOO-J.  Defensively  copy  mutable  inputs  and  mutable  internal  components2”  for 
more  information).  The  builder  class  does  not  violate  guideline  “SCP03-J.  Do  not  expose  sen¬ 
sitive  private  members  of  the  outer  class  from  within  a  nested  class2”  because  it  maintains  a  copy 
of  the  variables  defined  in  the  scope  of  the  containing  class.  The  private  members  within  the 
nested  class  take  precedence,  and  as  a  result,  do  not  break  encapsulation. 

2.5.3  Risk  Assessment 


Using  method  chaining  in  multithreaded  environments  without  performing  external  locking  can 
lead  to  nondeterministic  behavior. 
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2.6  VNA05-J.  Ensure  atomicity  when  reading  and  writing  64-bit  values 

The  Java  Language  Specification  allows  64-bit  long  and  double  values  to  be  treated  as  two  32- 
bit  values.  For  example,  a  64-bit  write  operation  may  be  performed  as  two  separate,  32-bit  opera¬ 
tions. 

According  to  the  Java  Language  Specification,  Section  1 7.7,  “Non-atomic  Treatment  of  double 
and  long”  [Gosling  2005] 

...  this  behavior  is  implementation  specific;  Java  virtual  machines  are  free  to  perform  writes 
to  long  and  double  values  atomically  or  in  two  parts.  For  the  purposes  of  the  Java  pro¬ 
gramming  language  memory  model,  a  single  write  to  a  non-volatile  long  or  double  value 
is  treated  as  two  separate  writes:  one  to  each  32-bit  half.  This  can  result  in  a  situation  where 
a  thread  sees  the  first  32  bits  of  a  64  bit  value  from  one  write,  and  the  second  32  bits  from 
another  write. 

This  behavior  can  result  in  indeterminate  values  being  read  in  code  that  is  required  to  be  thread- 
safe. 

2.6.1  Noncompliant  Code  Example 

In  this  noncompliant  code  example,  if  one  thread  repeatedly  calls  the  assignValue  ( )  method 
and  another  thread  repeatedly  calls  the  printLong  ( )  method,  the  printLong  ( )  method  could 
occasionally  print  a  value  of  i  that  is  neither  zero  nor  the  value  of  the  j  argument. 

class  LongContainer  { 
private  long  i  =  0; 

void  assignValue (long  j)  { 

i  =  j; 

} 

void  printLong ()  { 

System. out .println ( "i  =  "  +  i) ; 

} 


A  similar  problem  may  occur  if  i  is  declared  double. 

2.6.2  Compliant  Solution  (Volatile) 

This  compliant  solution  declares  i  volatile.  Writes  and  reads  of  long  and  double  volatile  values 
are  always  atomic. 

class  LongContainer  { 

private  volatile  long  i  =  0; 

void  assignValue (long  j)  { 

i  =  j; 

I 
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void  printLongO  { 

System. out. println ("i  =  ' 

} 

} 

'  +  i); 

It  is  important  to  ensure  that  the  argument  to  the  assignValue  ( )  method  is  obtained  from  a 
volatile  variable  or  as  a  result  of  explicitly  passing  an  integer  value.  Otherwise,  a  read  of  the  vari¬ 
able  argument  can,  itself,  expose  a  vulnerability. 

Semantics  of  volatile  do  not  guarantee  the  atomicity  of  compound  operations  that  involve 
read-modify-write  sequences  such  as  incrementing  a  value.  See  guideline  “VNA02-J.  Ensure  that 
compound  operations  on  shared  variables  are  atomic”  on  page  16  for  more  information. 

2.6.3  Exceptions 

VNA05-EX1:  If  all  reads  and  writes  of  64-bit  long  and  double  values  occur  within  a  synchro¬ 
nized  region,  the  atomicity  of  the  read/write  is  guaranteed.  That  guarantee  requires  that  no  unsyn¬ 
chronized  methods  in  the  class  expose  the  value  and  that  the  value  is  inaccessible  (directly  or  indi¬ 
rectly)  from  other  code.  (For  more  information,  see  guideline  “VNA02-J.  Ensure  that  compound 
operations  on  shared  variables  are  atomic”  on  page  16.) 

VNA05-EX2:  This  guideline  can  be  ignored  for  systems  that  guarantee  that  64-bit,  long  and 
double  values  are  read  and  written  as  atomic  operations. 

2.6.4  Risk  Assessment 


Failure  to  ensure  the  atomicity  of  operations  involving  64-bit  values  in  multithreaded  applications 
can  result  in  reading  and  writing  indeterminate  values.  Many  JVMs  read  and  write  64-bit  values 
atomically,  even  though  the  specification  does  not  require  them  to. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

VNA05-  J 

low 

unlikely 

medium 

P2 

L3 

2.6.5  References 


[Goetz  2004c] 
[Goetz  2006] 
[Gosling  2005] 
[MITRE  2010] 


Section  3.1.2,  “Non-Atomic  64-Bit  Operations” 

Section  17.7,  “Non-Atomic  Treatment  of  double  and  long” 
OWE  ID  667,  “Insufficient  Locking” 
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2.7  VNA06-J.  Do  not  assume  that  declaring  an  object  reference  volatile  guarantees 
visibility  of  its  members 

According  to  the  Java  Language  Specification,  Section  8. 3. 1.4,  “volatile  Fields”  [Gosling 
2005] 

A  field  may  be  declared  volatile,  in  which  case  the  Java  memory  model  (§17)  ensures 
that  all  threads  see  a  consistent  value  for  the  variable. 

Notably,  this  applies  only  to  primitive  fields  and  immutable  member  objects.  The  visibility  guar¬ 
antee  does  not  extend  to  non-thread-safe  mutable  objects,  even  if  their  references  are  declared 
volatile.  A  thread  may  not  observe  a  recent  write  from  another  thread  to  a  member  field  of  such  an 
object.  Declaring  an  object  volatile  to  ensure  the  visibility  of  its  state  does  not  work  without  the 
use  of  synchronization,  unless  the  object  is  immutable.  If  the  object  is  mutable  and  not  thread- 
safe,  other  threads  might  see  a  partially  constructed  object  or  an  object  in  a  (temporarily)  inconsis¬ 
tent  state  [Goetz  2006c]. 

Technically,  the  object  does  not  have  to  be  strictly  immutable  to  be  used  safely.  If  it  can  be  de¬ 
termined  that  a  member  object  is  thread-safe  by  design,  the  field  that  holds  its  reference  may  be 
declared  volatile.  Flowever,  this  approach  to  declaring  elements  volatile  decreases  maintainability 
and  should  be  avoided. 

2.7.1  Noncompliant  Code  Example  (Arrays) 

This  noncompliant  code  example  shows  an  array  object  that  is  declared  volatile. 

final  class  Foo  { 

private  volatile  int[]  arr  =  new  int[20]; 

public  int  getFirstf)  { 
return  arr[0]; 

I 

public  void  setFirst(int  n)  { 
arr[0]  =  n; 

} 

n  ... 

1 


Values  assigned  to  an  array  element  by  one  thread,  for  example,  by  calling  setFirst  ( ) ,  might 
not  be  visible  to  another  thread  calling  getFirst  ( )  because  the  volatile  keyword  only 
makes  the  array  reference  visible  and  does  not  affect  the  actual  data  contained  within  the  array. 

The  problem  occurs  because  there  is  no  happens-before  relationship  between  the  thread  that  calls 
setFirst  ( )  and  the  thread  that  calls  getFirst  ( ) .  A  happens-before  relationship  exists  be¬ 
tween  a  thread  that  writes  to  a  volatile  variable  and  a  thread  that  subsequently  reads  it.  Flowever, 
this  code  is  neither  writing  to  nor  reading  from  a  volatile  variable. 
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2.7.2  Compliant  Solution  (AtomicIntegerArray) 

To  ensure  that  the  writes  to  array  elements  are  atomic  and  the  resulting  values  are  visible  to  other 
threads,  this  compliant  solution  uses  the  AtomicIntegerArray  class  defined  in 

j  ava . util . concurrent . atomic . 

final  class  Foo  { 

private  final  AtomicIntegerArray  atomicArray  =  new  AtomicIntegerArray (20) ; 

public  int  getFirstO  { 

return  atomicArray . get (0 ) ; 

I 

public  void  setFirst(int  n)  { 
atomicArray. set (0,  10); 

1 

II  ... 

} 


AtomicIntegerArray  guarantees  a  happens-before  relationship  between  a  thread  that  calls 
atomicArray .  set  ( )  and  a  thread  that  subsequently  calls  atomicArray .  get  ( ) . 

2.7.3  Compliant  Solution  (Synchronization) 

To  ensure  visibility,  accessor  methods  may  synchronize  access,  while  performing  operations  on 
non-volatile  elements  of  an  array  that  is  declared  volatile.  Note  that  the  code  is  thread-safe,  even 
though  the  array  reference  is  non-volatile. 

final  class  Foo  { 

private  int[]  arr  =  new  int [20]; 

public  synchronized  int  getFirstO  { 
return  arr[0]; 

1 

public  synchronized  void  setFirst(int  n)  { 
arr[0]  =  n; 

1 

} 

Synchronization  establishes  a  happens-before  relationship  between  the  thread  that  calls 
setFirst  ( )  and  the  thread  that  subsequently  calls  getFirst  ( ) ,  guaranteeing  visibility. 

2.7.4  Noncompliant  Code  Example  (Mutable  Object) 

This  noncompliant  code  example  declares  the  Properties  instance  field  volatile.  The  instance 
of  the  Properties  object  can  be  mutated  using  the  put  ( )  method,  and  that  makes  the 
properties  field  mutable. 
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final  class  Foo  { 

private  volatile  Properties  properties; 
public  Foo()  { 

properties  =  new  Properties () ; 

/ /  Load  some  useful  values  into  properties 

1 

public  String  get (String  s)  { 

return  properties . getProperty (s ) ; 

! 

public  void  put (String  key.  String  value)  { 

//  Validate  the  values  before  inserting 
if  ( lvalue. matches (" [\\w] *") )  { 

throw  new  IllegalArgumentException ( ) ; 

| 

properties . setProperty (key,  value) ; 

} 

Interleaved  calls  to  get  ( )  and  put  ( )  may  result  in  internally  inconsistent  values  being  retrieved 
from  the  Properties  object  because  the  operations  within  put  ( )  modify  its  state.  Declaring 
the  object  volatile  does  not  eliminate  this  data  race. 

There  is  no  time-of-check-to-time-of-use  (TOCTOU)  vulnerability  in  put  ( ) ,  despite  the  presence 
of  the  validation  logic  because  the  validation  is  performed  on  the  immutable  value  argument  and 
not  the  shared  Properties  instance. 

2.7.5  Noncompliant  Code  Example  (Volatile-Read,  Synchronized-Write) 

This  noncompliant  code  example  attempts  to  use  the  volatile-read,  synchronized-write  technique 
described  by  Goetz  [Goetz  2006c].  The  properties  field  is  declared  volatile  to  synchronize  its 
reads  and  writes.  The  put  ( )  method  is  also  synchronized  to  ensure  that  its  statements  are  ex¬ 
ecuted  atomically. 

final  class  Foo  { 

private  volatile  Properties  properties; 
public  Foo()  { 

properties  =  new  Properties  () ; 

//  Load  some  useful  values  into  properties 

} 

public  String  get (String  s)  { 

return  properties . getProperty (s ) ; 

| 

public  synchronized  void  put (String  key,  String  value)  { 
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//  Validate  the  values  before  inserting 
if  ( lvalue. matches (" [\\w] *") )  { 

throw  new  IllegalArgumentException () ; 

} 

properties . setProperty (key,  value) ; 

} 

} 

The  volatile-read,  synchronized-write  technique  uses  synchronization  to  preserve  the  atomicity  of 
compound  operations,  such  as  increment,  and  provides  faster  access  times  for  atomic  reads.  How¬ 
ever,  it  does  not  work  with  mutable  objects  because  the  visibility  of  volatile  object  references 
does  not  extend  to  object  members.  Consequently,  there  is  no  happens-before  relationship  be¬ 
tween  the  write  and  a  subsequent  read  of  the  property. 

This  technique  is  also  discussed  in  guideline  “VNA02-J.  Ensure  that  compound  operations  on 
shared  variables  are  atomic”  on  page  16. 

2.7.6  Compliant  Solution  (Synchronization) 

This  compliant  solution  uses  method  synchronization  to  guarantee  visibility. 

final  class  Foo  { 

private  final  Properties  properties; 
public  Food  { 

properties  =  new  Properties!); 

//  Load  some  useful  values  into  properties 

I 

public  synchronized  String  get (String  s)  { 
return  properties . getProperty (s ) ; 

| 

public  synchronized  void  put (String  key,  String  value)  { 

//  Validate  the  values  before  inserting 
if  ( lvalue. matches (" [\\w] *") )  { 

throw  new  IllegalArgumentException () ; 

1 

properties . setProperty (key,  value) ; 

} 

} 

The  properties  field  does  not  need  to  be  volatile  because  the  methods  are  synchronized.  The 
field  is  declared  final  so  that  its  reference  is  not  published  when  it  is  in  a  partially  initialized  state 
(see  guideline  “TSM03-J.  Do  not  publish  partially  initialized  objects”  on  page  162  for  more  in¬ 
formation). 
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2.7.7  Noncompliant  Code  Example  (Mutable  Sub-Object) 

In  this  noncompliant  code  example,  the  volatile  format  field  is  used  to  store  a  reference  to  a 
mutable  object,  j  ava .  text .  DateFormat. 

final  class  DateHandler  { 

private  static  volatile  DateFormat  format  = 

DateFormat . getDatelnstance (DateFormat .MEDIUM) ; 

public  static  Date  parse (String  str)  throws  ParseException  { 
return  format .parse (str) ; 

| 

} 

Because  DateFormat  is  not  thread-safe  [Sun  2009c],  the  parse  ( )  method  might  return  a  value 
for  Date  that  does  not  correspond  to  the  str  argument. 

2.7.8  Compliant  Solution  (Instance  Per  Call/Defensive  Copying) 

This  compliant  solution  creates  and  returns  a  new  DateFormat  instance  for  every  invocation  of 
the  parse  ( )  method  [Sun  2009c]. 

final  class  DateHandler  { 

public  static  Date  parse (String  str)  throws  ParseException  { 

return  DateFormat . getDatelnstance (DateFormat .MEDIUM) .parse (str) ; 

} 

} 


This  solution  does  not  violate  guideline  “OBJ  1 1  -J.  Defensively  copy  private  mutable  class  mem¬ 
bers  before  returning  their  references”  '  because  the  class  no  longer  contains  internal  mutable 
state. 

2.7.9  Compliant  Solution  (Synchronization) 

This  compliant  solution  synchronizes  statements  within  the  parse  ( )  method,  making 
DateHandler  thread-safe  [Sun  2009c]. 

final  class  DateHandler  { 

private  static  DateFormat  format= 

DateFormat . getDatelnstance (DateFormat .MEDIUM) ; 

public  static  Date  parse (String  str)  throws  ParseException  { 
synchronized  (format)  { 
return  format .parse (str ) ; 

I 

I 

} 


This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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2.7.10  Compliant  Solution  (ThreadLocal  Storage) 

This  compliant  solution  uses  a  ThreadLocal  object  to  create  a  separate  DateFormat  instance 
per  thread. 

final  class  DateHandler  { 

private  static  final  ThreadLocal<DateFormat>  format  = 
new  ThreadLocal<DateFormat> ( )  { 

SOverride  protected  DateFormat  initialValue ()  { 

return  DateFormat . getDatelnstance (DateFormat .MEDIUM) ; 

I 

}; 

II  ... 

1 

2.7.11  Risk  Assessment 


Incorrectly  assuming  that  declaring  a  field  volatile  guarantees  that  the  visibility  of  a  referenced 
object’s  members  can  cause  threads  to  observe  stale  values. 
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Mutable  Statics 
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3  Lock  (LCK)  Guidelines 


3.1  LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that  may 
interact  with  untrusted  code 

The  synchronized  keyword  is  used  to  acquire  a  mutual-exclusion  lock  so  that  no  other  thread 
can  acquire  the  lock  while  it  is  being  held  by  the  executing  thread.  There  are  two  ways  to  syn¬ 
chronize  access  to  shared  mutable  variables:  method  synchronization  and  block  synchronization. 

A  method  declared  as  synchronized  always  uses  the  object’s  monitor  (intrinsic  lock),  as  does  code 
that  synchronizes  on  the  this  reference  using  a  synchronized  block.  Poorly  synchronized  code  is 
prone  to  contention  and  deadlock.  An  attacker  can  manipulate  the  system  to  trigger  these  condi¬ 
tions  and  cause  a  denial  of  service  by  obtaining  and  indefinitely  holding  the  intrinsic  lock  of  an 
accessible  class. 

This  vulnerability  can  be  prevented  using  a  j  ava .  lang .  Ob j  ect  declared  private  and  final 
within  the  class.  The  object  must  be  used  explicitly  for  locking  purposes  in  synchronized  blocks 
within  the  class’s  methods.  This  intrinsic  lock  is  associated  with  the  instance  of  the  private  object 
and  not  the  class.  Consequently,  there  is  no  lock  contention  between  this  class’s  methods  and  the 
methods  of  a  hostile  class.  Bloch  refers  to  this  technique  as  the  “private  lock  object”  idiom  [Bloch 
2001], 

Static  state  has  the  same  potential  problem.  If  a  static  method  is  declared  synchronized,  the  intrin¬ 
sic  lock  of  the  class  object  is  acquired  before  any  statements  in  its  body  are  executed,  and  the  lock 
is  released  when  the  method  completes.  Any  untrusted  code  that  can  access  an  object  of  the  class, 
or  a  subclass,  can  use  the  getClass  ( )  method  to  gain  access  to  the  class  lock.  Static  data  can  be 
protected  by  locking  on  a  private  static  final  Ob  j  ect.  Reducing  the  accessibility  of  the  class  to 
package-private  adds  further  protection  against  untrusted  callers. 

This  idiom  is  also  suitable  for  classes  designed  for  inheritance.  If  a  superclass  thread  requests  a 
lock  on  the  object’s  monitor,  a  subclass  thread  can  interfere  with  its  operation.  For  example,  a 
subclass  may  use  the  superclass  object’s  intrinsic  lock  for  performing  unrelated  operations,  caus¬ 
ing  significant  lock  contention  and  deadlock.  Separating  the  locking  strategy  of  the  superclass 
from  that  of  the  subclass  ensures  that  they  do  not  share  a  common  lock.  It  also  permits  fine¬ 
grained  locking  because  multiple  lock  objects  can  be  used  for  unrelated  operations,  increasing  the 
overall  responsiveness  of  the  application. 

An  object  should  use  a  private  final  lock  object  rather  than  its  own  intrinsic  lock  unless  the  class 
can  guarantee  that  untrusted  code  cannot 

•  subclass  the  class  or  its  superclass  (trusted  code  is  allowed  to  subclass  the  class) 

•  create  an  object  of  the  class,  its  superclass,  or  subclass 

•  access  or  acquire  an  object  instance  of  the  class,  its  superclass,  or  subclass 

If  a  class  uses  a  private  final  lock  to  synchronize  shared  data,  subclasses  must  also  use  a  private 
final  lock.  However,  if  a  class  uses  intrinsic  synchronization  over  the  class  object  without  docu¬ 
menting  its  locking  policy,  subclasses  may  not  use  intrinsic  synchronization  over  their  own  class 
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object,  unless  they  explicitly  document  their  locking  policy.  If  the  superclass  documents  its  policy 
by  stating  that  client-side  locking  is  supported,  the  subclasses  have  the  option  of  choosing  be¬ 
tween  intrinsic  locking  over  the  class  object  and  a  private  lock.  Regardless  of  which  is  chosen, 
subclasses  must  document  their  locking  policy.  See  guideline  “TSMOO-J.  Do  not  override  thread- 
safe  methods  with  methods  that  are  not  thread-safe”  on  page  145  for  related  information. 

If  all  of  these  restrictions  are  not  met,  the  object’s  intrinsic  lock  is  not  trustworthy.  If  they  are  met, 
the  object  gains  no  significant  security  from  using  a  private  final  lock  object  and  may  synchronize 
using  its  own  intrinsic  lock.  However,  it  is  still  best  to  use  block  synchronization  with  a  private 
final  lock  object  instead  of  method  synchronization  when  the  method  contains  non-atomic  opera¬ 
tions  that  either  do  not  require  any  synchronization  or  can  use  a  more  fine-grained  locking  scheme 
involving  multiple  private  final  lock  objects.  Non-atomic  operations  can  be  decoupled  from  those 
that  require  synchronization  and  executed  outside  the  synchronized  block.  For  this  reason  and 
maintainability  reasons,  block  synchronization  using  a  private  final  lock  object  is  generally  rec¬ 
ommended. 

3.1.1  Noncompliant  Code  Example  (Method  Synchronization) 

This  noncompliant  code  example  exposes  instances  of  the  SomeObject  class  to  untrusted  code. 

public  class  SomeObject  { 

public  synchronized  void  changeValue ( )  {  //  Locks  on  the  object's  monitor 

II  ... 

1 

t 

//  Untrusted  code 

SomeObject  SomeObject  =  new  SomeObject  ()  ; 
synchronized  (SomeObject)  { 
while  (true)  { 

Thread. sleep ( Integer ,MAX_VALUE) ;  //  Indefinitely  delay  SomeObject 

I 

1 


The  untrusted  code  attempts  to  acquire  a  lock  on  the  object’s  monitor  and,  upon  succeeding,  in¬ 
troduces  an  indefinite  delay  that  prevents  the  synchronized  changeValue  ( )  method  from 
acquiring  the  same  lock.  Note  that  in  the  untrusted  code,  the  attacker  intentionally  violates  guide¬ 
line  “LCK09-J.  Do  not  perform  operations  that  may  block  while  holding  a  lock”  on  page  77. 

3.1.2  Noncompliant  Code  Example  (Public  Non-Final  Lock  Object) 

This  noncompliant  code  example  locks  on  a  public  non-final  object  in  an  attempt  to  use  a  lock 
other  than  Some  Ob  j  ect’s  intrinsic  lock. 

public  class  SomeObject  { 

public  Object  lock  =  new  Object (); 

public  void  changeValue ( )  { 
synchronized  (lock)  { 
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II  ... 

I 

I 

1 

However,  it  is  possible  for  untrusted  code  to  change  the  value  of  the  lock  object  and  disrupt  prop¬ 
er  synchronization. 

3.1.3  Noncompliant  Code  Example  (Publicly  Accessible  Non-Final  Lock  Object) 

This  noncompliant  code  example  synchronizes  on  a  private  but  non-final  field. 

public  class  SomeObject  { 

private  volatile  Object  lock  =  new  Object  (); 

public  void  changeValue ( )  { 
synchronized  (lock)  { 

II  ... 

1 

1 

public  void  setLock (Object  lockValue)  { 
lock  =  lockValue; 

1 


Any  thread  can  modify  the  field’s  value  to  refer  to  a  different  object  in  the  presence  of  an  accessor 
such  as  setLock  ( ) .  That  modification  might  cause  two  threads  that  intend  to  lock  on  the  same 
object  to  lock  on  different  objects,  thereby  enabling  them  to  execute  the  two  critical  sections  in  an 
unsafe  manner.  For  example,  if  one  thread  is  in  its  critical  section  and  the  lock  is  changed,  a 
second  thread  will  lock  on  the  new  object  instead  of  the  old  one. 

A  class  that  does  not  provide  any  accessible  methods  to  change  the  lock  is  secure  against  un¬ 
trusted  manipulation.  However,  it  is  susceptible  to  inadvertent  modification  by  the  programmer. 
For  maintainability  reasons,  eliminating  the  accessor  method  (which  is  presumably  needed  for 
other  reasons)  is  not  the  preferred  solution. 

3.1.4  Noncompliant  Code  Example  (Public  Final  Lock  Object) 

This  noncompliant  code  example  uses  a  public  final  lock  object. 

public  class  SomeObject  { 

public  final  Object  lock  =  new  Object  (); 

public  void  changeValue ( )  { 
synchronized  (lock)  { 

II  ... 

) 

} 
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//  Untrusted  code 

SomeObject  someObject  =  new  SomeObject  ()  ; 
someOb j  ect . lock . wait ( ) 


Untrusted  code  that  has  the  ability  to  create  an  instance  of  the  class  or  has  access  to  an  already 
created  instance  can  invoke  the  wait  ( )  method  on  the  publicly  accessible  lock,  causing  the 
lock  in  the  changeValue  ( )  method  to  be  released  immediately.  Furthermore,  if  the  method 
invokes  lock .  wait  ( )  from  its  body  and  does  not  test  a  condition  predicate,  it  will  be  vulnerable 
to  malicious  notifications.  (See  guideline  “THI03-J.  Always  invoke  wait()  and  await()  methods 
inside  a  loop”  on  page  101  for  more  information.) 

3.1.5  Compliant  Solution  (Private  Final  Lock  Object) 

Thread-safe  public  classes  that  may  interact  with  untrusted  code  must  use  a  private  final  lock  ob¬ 
ject.  Existing  classes  that  use  intrinsic  synchronization  must  be  refactored  to  use  block  synchroni¬ 
zation  on  such  an  object.  In  this  compliant  solution,  calling  changeValue  ( )  obtains  a  lock  on  a 
private  final  Ob  j  ect  instance  that  is  inaccessible  from  callers  outside  the  class’s  scope. 

public  class  SomeObject  { 

private  final  Object  lock  =  new  Object ();  //  private  final  lock  object 

public  void  changeValue ( )  { 

synchronized  (lock)  {  //  Locks  on  the  private  Object 

II  ... 

} 

} 

} 


A  private  final  lock  object  can  only  be  used  with  block  synchronization.  Block  synchronization  is 
preferred  over  method  synchronization,  because  operations  that  do  not  require  synchronization 
can  be  moved  outside  the  synchronized  region,  reducing  lock  contention  and  blocking.  Note  that 
there  is  no  need  to  declare  lock  volatile  because  of  the  strong  visibility  semantics  of  final  fields. 
Instead  of  using  setter  methods  to  change  the  lock,  declare  and  use  multiple,  private  final  lock 
objects  to  satisfy  the  granularity  requirements. 

3.1.6  Noncompliant  Code  Example  (Static) 

This  noncompliant  code  example  exposes  the  class  object  of  SomeObject  to  untrusted  code. 

public  class  SomeObject  { 

//  changeValue  locks  on  the  class  object's  monitor 
public  static  synchronized  void  changeValue ( )  { 

n  ... 

I 

I 

//  Untrusted  code 

synchronized  (SomeOb j ect . class )  { 
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while  (true)  { 

Thread. sleep ( Integer ,MAX_VALUE) ;  //  Indefinitely  delay  someObject 

1 

} 

The  untrusted  code  attempts  to  acquire  a  lock  on  the  class  object’s  monitor  and,  upon  succeeding, 
introduces  an  indefinite  delay  that  prevents  the  synchronized  changeValue  ( )  method  from  ac¬ 
quiring  the  same  lock. 

A  compliant  solution  must  comply  with  guideline  “LCK05-J.  Synchronize  access  to  static  fields 
that  may  be  modified  by  untrusted  code”  on  page  59.  However,  in  the  untrusted  code,  the  attacker 
intentionally  violates  guideline  “LCK09-J.  Do  not  perform  operations  that  may  block  while  hold¬ 
ing  a  lock”  on  page  77. 

3.1.7  Compliant  Solution  (Static) 

Thread-safe  public  classes  that  may  interact  with  untrusted  code  and  use  intrinsic  synchronization 
over  the  class  object  must  be  refactored  to  use  a  static  private  final  lock  object  and  block  synchro¬ 
nization. 

public  class  SomeObject  { 

private  static  final  Object  lock  =  new  Object ();  //  private  final  lock  object 

public  static  void  changeValue ( )  { 

synchronized  (lock)  {  //  Locks  on  the  private  Object 

II  ... 

} 

! 

} 

In  this  compliant  solution,  changeValue  ( )  obtains  a  lock  on  a  static  private  Object  that  is 
inaccessible  to  the  caller. 
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3.1.8  Exceptions 

LCK00-EX1:  A  class  may  violate  this  guideline,  if  all  the  following  conditions  are  met: 

•  It  sufficiently  documents  that  callers  must  not  pass  objects  of  this  class  to  untrusted  code. 

•  The  class  does  not  invoke  methods  on  objects  of  any  untrusted  classes  that  violate  this  guide¬ 
line  directly  or  indirectly. 

•  The  synchronization  policy  of  the  class  is  documented  properly. 

A  client  may  use  a  class  that  violates  this  guideline,  if  all  the  following  conditions  are  met: 

•  The  class  does  not  pass  objects  of  this  class  to  untrusted  code. 

•  The  class  does  not  use  any  untrusted  classes  that  violate  this  guideline  directly  or  indirectly. 

LCK00-EX2:  If  a  superclass  of  the  class  documents  that  it  supports  client-side  locking  and  syn¬ 
chronizes  on  its  class  object,  the  class  can  support  client-side  locking  in  the  same  way  and  docu¬ 
ment  this  policy. 

LCK00-EX3:  A  package-private  class  may  violate  this  guideline  because  its  accessibility  protects 
against  untrusted  callers.  However,  this  condition  should  be  documented  explicitly  so  that  trusted 
code  within  the  same  package  does  not  reuse  or  change  the  lock  object  inadvertently. 

3.1.9  Risk  Assessment 

Exposing  the  class  object  to  untrusted  code  can  result  in  a  denial  of  service. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCKOO-J 

low 

probable 

medium 

P4 

L3 

3.1.10  References 

[Bloch  2001]  Item  52:  “Document  Thread  Safety” 
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3.2  LCK01-J.  Do  not  synchronize  on  objects  that  may  be  reused 

Misuse  of  synchronization  primitives  is  a  common  source  of  concurrency  issues.  Synchronizing 
on  objects  that  may  be  reused  can  result  in  deadlock  and  nondeterministic  behavior. 

3.2.1  Noncompliant  Code  Example  (Boolean  Lock  Object) 

This  noncompliant  code  example  synchronizes  on  a  Boolean  lock  object. 

private  final  Boolean  initialized  =  Boolean . FALSE; 

public  void  doSomething ( )  { 

synchronized  (initialized)  { 

II  ... 

1 

} 

The  Boolean  type  is  unsuitable  for  locking  purposes  because  it  allows  only  two  values:  true  and 
false.  Boolean  literals  containing  the  same  value  share  unique  instances  of  the  Boolean  class  in 
the  JVM.  In  this  example,  initialized  references  the  instance  corresponding  to  the  value 
false.  If  any  other  code  inadvertently  synchronizes  on  a  Boolean  literal  with  the  value  false,  the 
lock  instance  is  reused  and  the  system  can  become  unresponsiveness  or  deadlocked. 

3.2.2  Noncompliant  Code  Example  (Boxed  Primitive) 

This  noncompliant  code  example  locks  on  a  boxed  Integer  object. 

int  lock  =  0; 

private  final  Integer  Lock  =  lock;  //  Boxed  primitive  Lock  is  shared 

public  void  doSomething ( )  { 

synchronized  (Lock)  { 

H  ... 

\ 

} 


Boxed  types  may  use  the  same  instance  for  a  range  of  integer  values  and  consequently  suffer  from 
the  same  problem  as  Boolean  constants.  If  the  value  of  the  primitive  can  be  represented  as  a 
byte,  the  wrapper  object  is  reused.  Note  that  the  use  of  the  boxed  Integer  wrapper  object  is  in¬ 
secure;  instances  of  the  Integer  object  constructed  using  the  new  operator  (new  Integ¬ 
er  (value) )  are  unique  and  not  reused.  In  general,  holding  a  lock  on  any  data  type  that  contains 
a  boxed  value  is  insecure. 
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3.2.3  Compliant  Solution  (integer) 

This  compliant  solution  recommends  locking  on  a  non-boxed  Integer.  The  doSomething  ( ) 
method  synchronizes  using  the  intrinsic  lock  of  the  Integer  instance,  Lock. 

int  lock  =  0; 

private  final  Integer  Lock  =  new  Integer (lock) ; 

public  void  doSomething ( )  { 

synchronized  (Lock)  { 

II  ... 

i 

i 

When  explicitly  constructed,  an  Integer  object  has  a  unique  reference  and  its  own  intrinsic  lock 
that  is  not  shared  with  other  Integer  objects  or  boxed  integers  having  the  same  value.  While 
this  is  an  acceptable  solution,  it  can  cause  maintenance  problems  because  developers  can  incor¬ 
rectly  assume  that  boxed  integers  are  appropriate  lock  objects.  A  more  appropriate  solution  is  to 
synchronize  on  a  private  final  lock  object  as  described  in  the  compliant  solution  in  Section  3.2.7. 

3.2.4  Noncompliant  Code  Example  (Interned  string  Object) 


This  noncompliant  code  example  locks  on  an  interned  String  object. 


private  final  String  lock  =  new  String ( "LOCK" ) 

. intern  ( ) ; 

public  void  doSomething ( )  { 

synchronized  (lock)  { 

n  ... 

} 

} 

According  to  the  Java  API  class  j  ava .  lang .  String  documentation  [Sun  2009c] 

When  the  intern  ()  method  is  invoked,  if  the  pool  already  contains  a  string  equal  to  this 
String  object  as  determined  by  the  equals  (Object)  method,  then  the  string  from  the 
pool  is  returned.  Otherwise,  this  String  object  is  added  to  the  pool  and  a  reference  to  this 
String  object  is  returned. 

Consequently,  an  interned  String  object  behaves  like  a  global  variable  in  the  JVM.  As  demon¬ 
strated  in  this  noncompliant  code  example,  even  if  every  instance  of  an  object  maintains  its  own 
lock  field,  the  field  references  a  common  String  constant.  Locking  on  String  constants  has 
the  same  problem  as  locking  on  Boolean  constants. 

Additionally,  hostile  code  from  any  other  package  can  exploit  this  vulnerability,  if  the  class  is 
accessible.  (For  more  information,  see  guideline  “LCK00-J.  Use  private  final  lock  objects  to  syn¬ 
chronize  classes  that  may  interact  with  untrusted  code”  on  page  4 1 .) 
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3.2.5  Noncompliant  Code  Example  (String  Literal) 

This  noncompliant  code  example  locks  on  a  final  String  literal. 

//  This  bug  was  found  in  jetty-6.1.3  BoundedThreadPool 
private  final  String  lock  =  "LOCK"; 

II  ... 

synchronized  (lock)  { 

II  ... 

} 

II  ... 

A  String  literal  is  a  constant  and  interned.  Consequently,  it  suffers  from  the  same  pitfalls  as  the 
preceding  noncompliant  code  example. 

3.2.6  Compliant  Solution  (String  Instance) 

This  compliant  solution  locks  on  a  String  instance  that  is  not  interned. 

private  final  String  lock  =  new  String ( "LOCK" ) ; 

public  void  doSomething ( )  { 

synchronized  (lock)  { 

II  ... 

} 

} 

A  String  instance  differs  from  a  String  literal.  The  instance  has  a  unique  reference  and  its 
own  intrinsic  lock  that  is  not  shared  by  other  String  object  instances  or  literals.  A  better  ap¬ 
proach  is  to  synchronize  on  a  private  final  lock  object  as  shown  in  the  following  compliant  solu¬ 
tion. 

3.2.7  Compliant  Solution  (Private  Final  Lock  Object) 

This  compliant  solution  synchronizes  on  a  private  final  lock  object.  This  is  one  of  the  few  cases 
where  a  j ava .  lang . Object  instance  is  useful. 

private  final  Object  lock  =  new  Object  (); 

public  void  doSomething ( )  { 

synchronized  (lock)  { 

//  ... 

} 

} 

For  more  information  on  using  an  Ob  j  ect  as  a  lock,  see  guideline  “LCKOO-J.  Use  private  final 
lock  objects  to  synchronize  classes  that  may  interact  with  untrusted  code”  on  page  41. 
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3.2.8  Risk  Assessment 


A  significant  number  of  concurrency  vulnerabilities  arise  from  locking  on  the  wrong  kind  of  ob¬ 
ject.  It  is  important  to  consider  the  properties  of  the  lock  object  rather  than  indiscreetly  scaveng¬ 
ing  for  objects  to  synchronize  on. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK01-  J 

medium 

probable 

medium 

P8 

L2 
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3.3  LCK02-J.  Do  not  synchronize  on  the  class  object  returned  by  getClass() 

Synchronizing  on  the  return  value  of  the  Ob  j  ect .  getClass  ( )  method  can  lead  to  unexpected 
behavior.  Whenever  the  implementing  class  is  subclassed,  the  subclass  locks  on  the  subclass’s 
type,  which  is  a  completely  different  Class  object. 

Section  4.3.2,  “The  Class  Object”  of  the  Java  Language  Specification  describes  how  method  syn¬ 
chronization  works  [Gosling  2005]: 

A  class  method  that  is  declared  synchronized  synchronizes  on  the  lock  associated  with 
the  Class  object  of  the  class. 

This  does  not  mean  that  a  subclass  using  getClass  ( )  can  only  synchronize  on  the  Class  ob¬ 
ject  of  the  base  class.  In  fact,  it  will  lock  on  its  own  Class  object,  which  may  or  may  not  be  what 
the  programmer  intended.  The  intent  should  be  clearly  documented  or  annotated.  Note  that  if  a 
subclass  does  not  override  an  accessible  noncomp liant  superclass’s  method,  it  inherits  the  method, 
which  may  lead  to  the  false  conclusion  that  the  superclass’s  intrinsic  lock  is  available  in  the  sub¬ 
class. 

When  synchronizing  on  a  class  literal,  the  corresponding  lock  object  should  not  be  accessible  to 
untrusted  code.  If  the  class  is  package-private,  callers  from  other  packages  may  not  access  the 
class  object,  ensuring  its  trustworthiness  as  an  intrinsic  lock  object.  For  more  information,  see 
guideline  “LCK00-J.  Use  private  final  lock  objects  to  synchronize  classes  that  may  interact  with 
untrusted  code”  on  page  4 1 . 

3.3.1  Noncompliant  Code  Example  (getClass  ()  Lock  Object) 

In  this  noncompliant  code  example,  the  parse  ( )  method  of  the  Base  class  parses  a  date  and 
synchronizes  on  the  class  object  returned  by  getClass  ( ) .  The  Derived  class  also  inherits  the 
parse  ( )  method.  However,  this  inherited  method  synchronizes  on  Derived’s  class  object  be¬ 
cause  of  the  particular  return  value  of  getClass  ( ) . 

The  Derived  class  also  adds  a  doSomethingAndParse  ( )  method  that  locks  on  the  class  ob¬ 
ject  of  the  Base  class  because  the  developer  misconstrued  that  the  parse  ( )  method  in  Base 
always  obtains  a  lock  on  the  Base  class  object,  and  doSomethingAndParse  ( )  must  follow 
the  same  locking  policy.  Consequently,  the  Derived  class  has  two  different  locking  strategies 
and  is  not  thread-safe. 

class  Base  { 

static  DateFormat  format  = 

DateFormat . getDatelnstance (DateFormat .MEDIUM) ; 

public  Date  parse (String  str)  throws  ParseException  { 
synchronized  (getClass ())  { 

return  format .parse (str ) ; 

} 

} 

} 
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class  Derived  extends  Base  { 

public  Date  doSomethingAndParse (String  str)  throws  ParseException  { 
synchronized (Base . class)  { 

II  ... 

return  format .parse (str ) ; 


} 

3.3.2  Compliant  Solution  (Class  Name  Qualification) 

In  this  compliant  solution,  the  class  name  providing  the  lock  (Base)  is  fully  qualified. 

class  Base  { 

static  DateFormat  format  = 

DateFormat . getDatelnstance (DateFormat .MEDIUM)  ; 

public  Date  parse (String  str)  throws  ParseException  { 
synchronized  (Base. class)  { 
return  format .parse (str ) ; 

} 

I 

I 

II... 

This  code  example  always  synchronizes  on  the  Base  .class  object,  even  if  it  is  called  from  a 
Derived  object. 

3.3.3  Compliant  Solution  (Class  .  f  orName  ( ) ) 

This  compliant  solution  uses  the  Class  .  f  orName  ( )  method  to  synchronize  on  the  Base  class’s 
Class  object. 

class  Base  { 

static  DateFormat  format  = 

DateFormat . getDatelnstance (DateFormat .MEDIUM)  ; 

public  Date  parse (String  str)  throws  ParseException  { 
synchronized  (Class . forName ( "Base" ) )  { 
return  format .parse (str ) ; 

1 

} 

} 

II  ... 
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It  is  important  that  (.intrusted  inputs  are  not  accepted  as  arguments  while  loading  classes  using 
Class  .  forName  ( ) .  See  guideline  “SEC05-J.  Do  not  expose  standard  APIs  that  use  the  imme¬ 
diate  caller’s  class  loader  instance  to  untrusted  code4”  for  more  information. 

3.3.4  Noncompliant  Code  Example  (getciass  ()  Lock  Object,  Inner  Class) 

This  noncompliant  code  example  synchronizes  on  the  class  object  returned  by  getciass  ( )  in 
the  parse  ( )  method  of  the  Base  class.  The  Base  class  also  has  a  nested  Helper  class  whose 
doSomethingAndParse  ( )  method  incorrectly  synchronizes  on  the  value  returned  by 

getciass ( )  . 

class  Base  { 

static  DateFormat  format  = 

DateFormat . getDatelnstance (DateFormat .MEDIUM)  ; 

public  Date  parse (String  str)  throws  ParseException  { 
synchronized  (getClassO)  { 
return  format .parse (str ) ; 

} 

1 

public  Date  doSomething (String  str)  throws  ParseException  { 
return  new  Helper (). doSomethingAndParse (str) ; 

i 

private  class  Helper  { 

public  Date  doSomethingAndParse (String  str)  throws  ParseException  { 
synchronized  (getciass  ()  )  {  //  Synchronizes  on  getClassO 

II  ... 

return  format .parse (str); 


} 

} 

The  call  to  getciass  ( )  in  the  Helper  class  returns  a  Helper  class  object  instead  of  the  Base 
class  object.  Consequently,  a  thread  that  calls  Base .  parse  ( )  locks  on  a  different  object  than  a 
thread  that  calls  Base .  doSomething  ( ) .  It  is  easy  to  overlook  concurrency  errors  in  inner 
classes  because  they  exist  within  the  body  of  the  containing  outer  class.  A  reviewer  might  incor¬ 
rectly  assume  that  the  two  classes  have  the  same  locking  strategy. 


This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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3.3.5  Compliant  Solution  (Class  Name  Qualification) 

This  compliant  solution  synchronizes  using  a  Base  class  literal  in  the  parse  ( )  and  doSome- 
thingAndParse  ( )  methods. 

class  Base  { 

II  ... 

public  Date  parse (String  str)  throws  ParseException  { 
synchronized  (Base. class)  { 
return  format .parse (str ) ; 

} 

1 

private  class  Helper  { 

public  Date  doSomethingAndParse (String  str)  throws  ParseException  { 
synchronized (Base . class )  {  //  Synchronizes  on  Base  class  literal 

//  ... 

return  format .parse (str); 


I 

1 

Consequently,  both  Base  and  Helper  lock  on  Base’s  intrinsic  lock.  Similarly,  the 
Class  .  f  orname  ( )  method  can  be  used  instead  of  a  class  literal. 

3.3.6  Risk  Assessment 

Synchronizing  on  the  class  object  returned  by  getClass  ( )  can  result  in  nondeterministic  beha¬ 
vior. 
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3.4  LCK03-J.  Do  not  synchronize  on  the  intrinsic  locks  of  high-level  concurrency 
objects 

It  is  inappropriate  to  lock  on  an  object  of  a  class  that  implements  one  or  both  of  the  following  in¬ 
terfaces  of  the  j  ava  .  util .  concurrent .  locks  package:  Lock  and  Condition.  Using  the 
intrinsic  locks  of  these  classes  is  a  questionable  practice  even  though  the  code  may  appear  to 
function  correctly.  This  problem  is  commonly  discovered  when  code  is  refactored  from  intrinsic 
locking  to  the  j  ava .  util .  concurrent  dynamic -locking  utilities. 

3.4.1  Noncompliant  Code  Example  (ReentrantLock  Lock  Object) 

The  doSomething  ( )  method  in  this  noncompliant  code  example  synchronizes  on  the  intrinsic 
lock  of  an  instance  of  ReentrantLock  instead  of  the  reentrant  mutual  exclusion  Lock  encapsu¬ 
lated  by  ReentrantLock. 

private  final  Lock  lock  =  new  ReentrantLock () ; 

public  void  doSomething ( )  { 

synchronized (lock)  { 

u  ... 

} 

} 

3.4.2  Compliant  Solution  (lock  ()  and  unlock  ()) 

Instead  of  using  the  intrinsic  locks  of  objects  that  implement  the  Lock  interface,  such  as  Reen¬ 
trantLock,  use  the  lock  ( )  and  unlock  ( )  methods  provided  by  the  Lock  interface. 

private  final  Lock  lock  =  new  ReentrantLock () ; 

public  void  doSomething ( )  { 

lock. lock ( ) ; 
try  { 

//  ... 

}  finally  { 

lock . unlock ( ) ; 

} 

} 

If  there  is  no  requirement  for  using  the  advanced  functionality  of  the  j  ava .  util .  concurrent 
package’s  dynamic-locking  utilities,  it  is  better  to  use  the  Executor  framework  or  other  concur¬ 
rency  primitives  such  as  synchronization  and  atomic  classes. 
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3.4.3  Risk  Assessment 


Synchronizing  on  the  intrinsic  lock  of  high-level  concurrency  utilities  can  cause  nondeterministic 
behavior  because  the  class  can  end  up  with  two  different  locking  policies. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK03-J 

medium 

probable 

medium 

P8 

L2 

3.4.4  References 

[Findbugs  2008] 

[Miller  2009] 

[Pugh  2008] 

[Sun  2009b] 

[Sun  2008a] 


Locking 

“Synchronization” 

Wrapper  Implementations 
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3.5  LCK04-J.  Do  not  synchronize  on  a  collection  view  if  the  backing  collection  is 
accessible 

The  j  ava .  util .  Collections  interface’s  documentation  [Sun  2009b]  warns  about  the  conse¬ 
quences  of  failing  to  synchronize  on  an  accessible  collection  object  when  iterating  over  its  view: 

It  is  imperative  that  the  user  manually  synchronize  on  the  returned  map  when  iterating  over 
any  of  its  collection  views.  .  .  Failure  to  follow  this  advice  may  result  in  non-deterministic 
behavior. 

A  class  that  uses  a  collection  view  instead  of  the  backing  collection  as  the  lock  object  may  end  up 
with  two  different  locking  strategies.  In  this  case,  if  the  backing  collection  is  accessible  to  mul¬ 
tiple  threads,  the  class  is  not  thread-safe. 

3.5.1  Noncompliant  Code  Example  (Collection  View) 

This  noncompliant  code  example  creates  two  views:  a  synchronized  view  of  an  empty  HashMap 
encapsulated  by  the  map  field  and  a  set  view  of  the  map’s  keys  encapsulated  by  the  set  field. 
This  example  synchronizes  on  the  set  view  [Sun  2008a]. 

//  map  has  package-private  accessibility 
final  Mapklnteger,  String>  map  = 

Collections . synchronizedMap (new  HashMapklnteger ,  String>()); 
private  final  Setklnteger>  set  =  map .  keyset  ()  ; 

public  void  doSomething ( )  { 

synchronized (set)  {  //  Incorrectly  synchronizes  on  set 

for  (Integer  k  :  set)  { 

II  ... 

} 

} 

} 


In  this  example,  HashMap  provides  the  backing  collection  for  Map,  which  provides  the  backing 
collection  for  Set,  as  shown  in  Figure  4: 


Figure  4:  How  Backing  Collection  Works  in  the  Collection  View,  Noncompliant  Code  Example 

HashMap  is  not  accessible,  but  the  map  view  is.  Because  the  set  view  is  synchronized  instead  of 
the  map  view,  another  thread  can  modify  the  contents  of  map  and  invalidate  the  k  iterator. 
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3.5.2  Compliant  Solution  (Collection  Lock  Object) 

This  compliant  solution  synchronizes  on  the  map  view  instead  of  the  set  view. 

//  map  has  package-private  accessibility 
final  Mapklnteger,  String>  map  = 

Collections . synchronizedMap (new  HashMapklnteger ,  String>()); 
private  final  Setklnteger>  set  =  map . keyset () ; 

public  void  doSomething ( )  { 

synchronized (map)  {  //  Synchronize  on  map,  not  set 

for  (Integer  k  :  set)  { 

//  ... 

} 

J 

} 


This  code  is  compliant  because  the  map’s  underlying  structure  cannot  be  changed  when  an  itera¬ 
tion  is  in  progress. 

3.5.3  Risk  Assessment 

Synchronizing  on  a  collection  view  instead  of  the  collection  object  can  cause  nondeterministic 
behavior. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK04-J 

low 

probable 

medium 

P8 

L2 

3.5.4  References 

[Sun  2009b]  Class  Collections 

[Sun  2008a]  Wrapper  Implementations 
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3.6  LCK05-J.  Synchronize  access  to  static  fields  that  may  be  modified  by  untrusted 
code 

Methods  that  can  be  invoked  from  untrusted  code  to  modify  a  static  field  must  synchronize  access 
to  that  field.  That  is  necessary  because  there  is  no  guarantee  that  untrusted  clients  will  externally 
synchronize  when  accessing  the  field.  Because  a  static  field  is  shared  by  all  clients,  untrusted 
clients  may  violate  the  contract  by  failing  to  provide  suitable  locking. 

According  to  Bloch  [Bloch  2008] 

If  a  method  modifies  a  static  field,  you  must  synchronize  access  to  this  field,  even  if  the  me¬ 
thod  is  typically  used  only  by  a  single  thread.  It  is  not  possible  for  clients  to  perform  external 
synchronization  on  such  a  method  because  there  can  be  no  guarantee  that  unrelated  clients 
will  do  likewise. 

Documented  design  intent  is  irrelevant  when  dealing  with  untrusted  code  because  an  attacker  can 
always  choose  to  ignore  the  documentation. 

3.6.1  Noncompliant  Code  Example 

This  noncompliant  code  example  does  not  synchronize  access  to  the  static  counter  field. 

/**  This  class  is  not  thread-safe  */ 
public  final  class  CountHits  { 
private  static  int  counter; 

public  void  incrementCounter ( )  { 

counter!!; 

I 

1 


This  class  definition  does  not  violate  guideline  “VNA02-J.  Ensure  that  compound  operations  on 
shared  variables  are  atomic”  on  page  16,  which  only  applies  to  classes  that  promise  thread-safety. 
However,  this  class  has  a  mutable  static  counter  field  that  is  modified  by  the  publicly  accessible 
incrementCounter  ( )  method.  Consequently,  this  class  cannot  be  used  securely  by  trusted 
client  code,  if  untrusted  code  can  purposely  fail  to  externally  synchronize  access  to  the  field. 
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3.6.2  Compliant  Solution 

This  compliant  solution  uses  a  static  private  final  lock  to  protect  the  counter  field  and,  conse¬ 
quently,  does  not  depend  on  any  external  synchronization.  This  solution  also  complies  with  guide¬ 
line  “LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that  may  interact  with  un¬ 
trusted  code”  on  page  41. 

/**  This  class  is  thread-safe  */ 
public  final  class  CountHits  { 
private  static  int  counter; 

private  static  final  Object  lock  =  new  Object  (); 

public  void  incrementCounter ( )  { 

synchronized  (lock)  { 
counter++; 

} 

} 

} 

3.6.3  Risk  Assessment 

Failing  to  internally  synchronize  access  to  static  fields  that  may  be  modified  by  untrusted  code 
will  result  in  incorrectly  synchronized  code,  if  the  author  of  the  untrusted  code  chooses  to  ignore 
the  synchronization  policy. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK05-  J 

low 

probable 

medium 

P4 

L3 

3.6.4  References 

[Bloch  2008]  Item  67:  “Avoid  excessive  synchronization” 

[Sun  2009b] 
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3.7  LCK06-J.  Do  not  use  an  instance  lock  to  protect  shared  static  data 

Shared  static  data  should  not  be  protected  using  instance  locks  because  they  are  ineffective  when 
two  or  more  instances  of  the  class  are  created.  Consequently,  shared  state  is  not  safe  for  concur¬ 
rent  access  unless  a  static  lock  object  is  used.  If  the  class  can  interact  with  untrusted  code,  the  lock 
must  also  be  private  and  final,  as  per  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  syn¬ 
chronize  classes  that  may  interact  with  untrusted  code”  on  page  4 1 . 

3.7.1  Noncompliant  Code  Example  (Non-Static  Lock  Object  for  Static  Data) 

This  noncompliant  code  example  uses  a  non-static  lock  object  to  guard  access  to  a  static 
counter  field.  If  two  Runnable  tasks  are  started,  they  will  create  two  instances  of  the  lock  ob¬ 
ject  and  lock  on  each  one  separately. 

public  final  class  CountBoxes  implements  Runnable  { 
private  static  volatile  int  counter; 

II  ... 

private  final  Object  lock  =  new  Object  (); 

@Override  public  void  run()  { 
synchronized (lock)  { 
counter++; 

II  ... 

} 

} 

public  static  void  main (String [ ]  args)  { 
for (int  i  =  0;  i  <  2;  i++)  { 

new  Thread (new  CountBoxes ()). start () ; 

} 

} 

} 

This  example  does  not  prevent  either  thread  from  observing  an  inconsistent  value  of  counter 
because  the  increment  operation  on  volatile  fields  is  non-atomic  in  the  absence  of  proper  synchro¬ 
nization  (see  guideline  “VNA02-J.  Ensure  that  compound  operations  on  shared  variables  are 
atomic”  on  page  16). 
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3.7.2  Noncompiiant  Code  Example  (Method  Synchronization  for  Static  Data) 

This  noncompiiant  code  example  uses  method  synchronization  to  protect  access  to  the  static  class 
counter  field. 

public  final  class  CountBoxes  implements  Runnable  { 
private  static  volatile  int  counter; 

H  ... 

public  synchronized  void  run()  { 
counter++; 

II  ... 

1 

II  ... 

} 

In  this  case,  the  intrinsic  lock  is  associated  with  each  instance  of  the  class  and  not  with  the  class 
itself.  Consequently,  threads  constructed  using  different  Runnable  instances  may  observe  incon¬ 
sistent  values  of  counter. 

3.7.3  Compliant  Solution  (Static  Lock  Object) 

This  compliant  solution  declares  the  lock  object  static  and  consequently  ensures  the  atomicity  of 
the  increment  operation. 

public  class  CountBoxes  implements  Runnable  { 
private  static  int  counter; 

//  ... 

private  static  final  Object  lock  =  new  Object (); 

public  void  run()  { 
synchronized (lock)  { 
counter++; 

//  ... 

} 

II  ... 

1 


There  is  no  need  to  declare  the  counter  variable  volatile  when  using  synchronization. 

3.7.4  Risk  Assessment 

Using  an  instance  lock  to  protect  shared  static  data  can  result  in  nondeterministic  behavior. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK06-  J 

medium 

probable 

medium 

P8 

L2 

3.7.5  References 

[Sun  2009b] 
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3.8  LCK07-J.  Avoid  deadlock  by  requesting  and  releasing  locks  in  the  same  order 

To  avoid  data  corruption  in  multithreaded  Java  programs,  shared  data  must  be  protected  from 
concurrent  modifications  and  accesses.  Locking  can  be  performed  at  the  object  level  using  syn¬ 
chronized  methods,  synchronized  blocks,  or  the  j  ava .  util .  concurrent  dynamic,  lock  ob¬ 
jects.  However,  excessive  use  of  locking  can  result  in  deadlock. 

Java  does  not  prevent  deadlock  or  require  its  detection  [Gosling  2005].  Deadlock  can  occur  when 
two  or  more  threads  request  and  release  locks  in  different  orders.  Consequently,  it  can  be  avoided 
by  acquiring  and  releasing  locks  in  the  same  order. 

Additionally,  synchronization  should  be  limited  to  cases  where  it  is  absolutely  necessary.  For  ex¬ 
ample,  the  paint  ( ) ,  dispose  ( ) ,  stop  ( ) ,  and  destroy  ( )  methods  should  never  be  syn¬ 
chronized  in  an  applet  because  they  are  always  called  and  used  from  dedicated  threads.  The 
Thread .  stop  ( )  and  Thread .  destroy  ( )  methods  are  deprecated.  For  more  information,  see 
guideline  “THI05-J.  Do  not  use  Thread. stop()  to  terminate  threads”  on  page  110. 

This  guideline  also  applies  to  programs  that  need  to  work  with  a  limited  set  of  resources.  For  ex¬ 
ample,  liveness  issues  can  arise  when  two  or  more  threads  are  waiting  for  each  other  to  release 
resources  such  as  database  connections.  These  issues  can  be  resolved  by  letting  each  waiting 
thread  retry  the  operation  at  random  intervals,  until  they  succeed  in  acquiring  the  resource  suc¬ 
cessfully. 

3.8.1  Noncompliant  Code  Example  (Different  Lock  Orders) 

This  noncompliant  code  example  can  deadlock  because  of  excessive  synchronization.  The 
balanceAmount  field  represents  the  total  balance  amount  available  for  a  particular 
BankAccount  object.  A  user  is  allowed  to  initiate  an  operation  that  atomically  transfers  a  speci¬ 
fied  amount  from  one  account  to  another. 

final  class  BankAccount  { 

private  double  balanceAmount;  //  Total  amount  in  bank  account 

BankAccount (double  balance)  { 
this .balanceAmount  =  balance; 

} 

//  Deposits  the  amount  from  this  object  instance  to  BankAccount  instance  argument  ba 
private  void  depositAmount (BankAccount  ba,  double  amount)  { 
synchronized  (this)  { 
synchronized (ba)  { 

if (amount  >  balanceAmount)  { 

throw  new  IllegalArgumentException ( "Transfer  cannot  be  completed"); 

} 

ba . balanceAmount  +=  amount; 
this . balanceAmount  -=  amount; 
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public  static  void  initiateTransfer (final  BankAccount  first, 
final  BankAccount  second,  final  double  amount)  { 

Thread  transfer  =  new  Thread (new  Runnable ()  { 

public  void  run()  { 

first . depositAmount (second,  amount) ; 

IM 

transfer . start ( ) ; 

| 

} 


Objects  of  this  class  are  prone  to  deadlock.  An  attacker  that  has  two  bank  accounts  can  construct 
two  threads  that  initiate  balance  transfers  from  two  different  BankAccount  object  instances,  a 
and  b.  For  example,  consider  the  following  code: 


BankAccount  a  =  new 
BankAccount  b  =  new 
initiateTransfer (a, 
initiateTransfer (b. 


BankAccount (5000)  ; 
BankAccount (6000)  ; 
b,  1000) ;  //  starts  thread  1 
a,  1000) ;  //  starts  thread  2 


Each  transfer  is  performed  in  its  own  thread.  The  first  thread  atomically  transfers  the  amount  from 
a  to  b  by  depositing  it  in  account  b  and  then  withdrawing  the  same  amount  from  a.  The  second 
thread  performs  the  reverse  operation;  that  is,  it  transfers  the  amount  from  b  to  a.  When  executing 
depositAmount  ( ) ,  the  first  thread  acquires  a  lock  on  object  a.  The  second  thread  could  acquire 
a  lock  on  object  b  before  the  first  thread  can.  Subsequently,  the  first  thread  would  request  a  lock 
on  b,  which  is  already  held  by  the  second  thread.  The  second  thread  would  request  a  lock  on  a, 
which  is  already  held  by  the  first  thread.  This  constitutes  a  deadlock  condition,  because  neither 
thread  can  proceed. 

This  noncompliant  code  example  may  or  may  not  cause  deadlock,  depending  on  the  scheduling 
details  of  the  platform.  Deadlock  will  occur  when  two  threads  request  the  same  two  locks  in  dif¬ 
ferent  orders  and  each  thread  obtains  a  lock  that  prevents  the  other  thread  from  completing  its 
transfer.  Deadlock  will  not  occur  when  two  threads  request  the  same  two  locks  but  one  thread 
completes  its  transfer  before  the  other  thread  begins.  Similarly,  deadlock  will  not  occur  if  the  two 
threads  request  the  same  two  locks  in  the  same  order  (which  would  happen  if  they  both  transfer 
money  from  one  account  to  a  second  account)  or  if  two  transfers  involving  distinct  accounts  occur 
concurrently. 

3.8.2  Compliant  Solution  (Private  Static  Final  Lock  Object) 

Deadlock  can  be  avoided  by  synchronizing  on  a  private  static  final  lock  object  before  performing 
any  account  transfers. 

final  class  BankAccount  { 

private  double  balanceAmount;  //  Total  amount  in  bank  account 
private  static  final  Object  lock  =  new  Object!); 

BankAccount (double  balance)  { 
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this . balanceAmount  =  balance; 

} 

//  Deposits  the  amount  from  this  object  instance  to  BankAccount  instance  argument  ba 
private  void  depositAmount (BankAccount  ba,  double  amount)  { 
synchronized  (lock)  { 

if  (amount  >  balanceAmount)  { 

throw  new  IllegalArgumentException ( "Transfer  cannot  be  completed"); 

} 

ba . balanceAmount  +=  amount; 
this . balanceAmount  -=  amount; 


public  static  void  initiateTransfer (final  BankAccount  first, 
final  BankAccount  second,  final  double  amount)  { 

Thread  transfer  =  new  Thread (new  Runnable ()  { 

@Override  public  void  run()  { 

first . depositAmount (second,  amount) ; 

} 

})  ; 

transfer . start  ( ) ; 

} 

} 

In  this  scenario,  deadlock  cannot  occur  when  two  threads  with  two  different  BankAccount  ob¬ 
jects  try  to  transfer  to  each  others’  accounts  simultaneously.  One  thread  will  acquire  the  private 
lock,  complete  its  transfer,  and  release  the  lock  before  the  other  thread  can  proceed. 

This  solution  comes  with  a  performance  penalty  because  a  private  static  lock  restricts  the 
system  to  performing  only  one  transfer  at  a  time.  Two  transfers  involving  four  distinct  accounts 
(with  distinct  target  accounts)  cannot  be  performed  concurrently.  This  penalty  increases  consider¬ 
ably  as  the  number  of  BankAccount  objects  increase.  Consequently,  this  solution  does  not  scale 
well. 

3.8.3  Compliant  Solution  (Ordered  Locks) 

This  compliant  solution  ensures  that  multiple  locks  are  acquired  and  released  in  the  same  order.  It 
requires  that  an  ordering  over  BankAccount  objects  is  available.  The  ordering  is  enforced  by 
having  the  BankAccount  class  implement  the  j  ava .  lang .  Comparable  interface  and  over¬ 
ride  the  compareTo  ( )  method. 

final  class  BankAccount  implements  Comparable<BankAccount>  { 
private  double  balanceAmount;  //  Total  amount  in  bank  account 
private  final  Object  lock; 

private  final  long  id;  //  Unique  for  each  BankAccount 
private  static  long  NextID  =  0;  //  Next  unused  ID 
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BankAccount (double  balance)  { 
this . balanceAmount  =  balance; 
this. lock  =  new  Object  (); 
this. id  =  this . NextID++; 

1 

SOverride  public  int  compareTo (BankAccount  ba)  { 

return  (this. id  >  ba.id)  ?  1  :  (this. id  <  ba.id)  ?  -1  :  0; 

I 

//  Deposits  the  amount  from  this  object  instance  to  BankAccount  instance  argument  ba 
public  void  depositAmount (BankAccount  ba,  double  amount)  { 

BankAccount  former,  latter; 
if  (compareTo (ba)  <  0)  { 

former  =  this; 
latter  =  ba; 

}  else  { 

former  =  ba; 
latter  =  this; 

} 

synchronized  (former)  { 
synchronized  (latter)  { 

if  (amount  >  balanceAmount)  { 

throw  new  IllegalArgumentException ( "Transfer  cannot  be  completed"); 

1 

ba . balanceAmount  +=  amount; 
this . balanceAmount  -=  amount; 

} 


public  static  void  initiateTransfer (final  BankAccount  first, 
final  BankAccount  second,  final  double  amount)  { 

Thread  transfer  =  new  Thread (new  Runnable ()  { 

@Override  public  void  run()  { 

first . depositAmount (second,  amount) ; 

} 

}) ; 

transfer . start  ( ) ; 

} 

} 

Whenever  a  transfer  occurs,  the  two  BankAccount  objects  are  ordered  so  that  the  first  ob¬ 
ject’s  lock  is  acquired  before  the  second  object’s  lock.  Consequently,  if  two  threads  attempt 
transfers  between  the  same  two  accounts,  they  will  both  try  to  acquire  the  first  account’s  lock  be¬ 
fore  the  second’s.  As  a  result,  one  thread  will  acquire  both  locks,  complete  the  transfer,  and  re¬ 
lease  both  locks  before  the  other  thread  can  proceed. 
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Unlike  in  the  previous  compliant  solution,  multiple  transfers  can  happen  concurrently,  as  long  as 
they  involve  distinct  target  accounts. 

3.8.4  Compliant  Solution  (ReentrantLock) 

In  this  compliant  solution,  each  BankAccount  has  an  associated 
j  ava  .  util .  concurrent .  locks  .  ReentrantLock.  This  design  permits  the 
depositAmount  ( )  method  to  try  to  acquire  the  locks  of  both  accounts  and  to  release  the  locks 
if  it  fails  and  try  again  later. 

final  class  BankAccount  { 

private  double  balanceAmount;  //  Total  amount  in  bank  account 
private  final  Lock  lock  =  new  ReentrantLock () ; 
private  final  Random  number  =  new  Random ( 123L) ; 

BankAccount (double  balance)  { 
this . balanceAmount  =  balance; 

} 

//  Deposits  amount  from  this  object  instance  to  BankAccount  instance  argument  ba 
private  void  depositAmount (BankAccount  ba,  double  amount) 

throws  InterruptedException  { 

while  (true)  { 

if  (this . lock. tryLock () )  { 

try  { 

if  (ba . lock. tryLock () )  { 

try  { 

if  (amount  >  balanceAmount)  { 

throw  new  IllegalArgumentException ( "Transfer  cannot  be  completed"); 

} 

ba . balanceAmount  +=  amount; 
this . balanceAmount  -=  amount; 
break; 

}  finally  { 

ba . lock . unlock ( )  ; 

} 

} 

}  finally  { 

this . lock . unlock ( )  ; 

} 

} 

int  n  =  number . nextlnt ( 1000 )  ; 

int  TIME  =  1000  +  n;  //  1  second  +  random  delay  to  prevent  livelock 
Thread. sleep (TIME) ; 


public  static  void  initiateTransfer (final  BankAccount  first, 
final  BankAccount  second,  final  double  amount)  { 
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Thread  transfer  =  new  Thread (new  Runnable ()  { 

public  void  run()  { 
try  { 

first . depositAmount (second,  amount) ; 

}  catch  (InterruptedException  e)  { 

Thread. cur rentThread (). interrupt () ;  //  Reset  interrupted  status 

i 

i 

}>  ? 

transfer . start ( ) ; 

f 

1 


Deadlock  is  impossible  in  this  compliant  solution  because  no  method  grabs  a  lock  and  holds  it 
indefinitely.  If  the  current  object’s  lock  is  acquired  but  the  second  lock  is  unavailable,  the  first 
lock  is  released  and  the  thread  sleeps  for  some  specified  amount  of  time  before  attempting  to 
reacquire  the  lock. 

Code  that  uses  this  lock  has  behavior  similar  to  that  of  synchronized  code  that  uses  the  traditional 
monitor  lock.  ReentrantLock  provides  several  other  capabilities.  For  example,  the 
tryLock  ( )  method  does  not  block  waiting,  if  another  thread  is  already  holding  the  lock.  The 
j  ava  .  util .  concurrent .  locks  .  ReentrantReadWriteLock  class  can  be  used  when 
some  threads  require  a  lock  to  write  information,  while  other  threads  require  the  lock  to  concur¬ 
rently  read  the  information. 

3.8.5  Noncompiiant  Code  Example  (Different  Lock  Orders,  Recursive) 

The  following  immutable  WebRequest  class  encapsulates  a  web  request  received  by  a  server: 

//  Immutable  WebRequest 
public  final  class  WebRequest  { 
private  final  long  bandwidth; 
private  final  long  responseTime; 


public  WebRequest ( long  bandwidth,  long  responseTime)  { 
this . bandwidth  =  bandwidth; 
this . responseTime  =  responseTime; 

} 


public  long  getBandwidth ( )  { 

return  bandwidth; 

) 


public  long  getResponseTime ( )  { 

return  responseTime; 


} 
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Each  request  has  a  response  time  associated  with  it,  along  with  a  measurement  of  the  network 
bandwidth  required  to  fulfill  the  request. 


This  noncompliant  code  example  monitors  web  requests  and  provides  routines  for  calculating  the 
average  bandwidth  and  response  time  required  to  service  incoming  requests. 


public  final  class  WebRequestAnalyzer  { 

private  final  Vector<WebRequest>  requests  =  new  Vector<WebRequest> ( ) ; 


public  boolean  addWebRequest (WebRequest  request)  { 

return  requests . add (new  WebRequest (request . getBandwidth () , 
request . getResponseTime ( ) ) ) ; 


public  double  getAverageBandwidth ( )  { 

if  (requests . size ( )  ==  0)  { 

throw  new  IllegalStateException  ("The  vector  is  empty!"); 

} 

return  calculateAverageBandwidth (0,  0)  ; 


public  double  getAverageResponseTime ( )  { 

if  (requests . size ( )  ==  0)  { 

throw  new  IllegalStateException ("The  vector  is  empty!"); 

1 

return  calculateAverageResponseTime (requests . size ( )  -  1,  0) ; 


private  double  calculateAverageBandwidth (int  i,  long  bandwidth)  { 
if  (i  ==  requests . size () )  { 

return  bandwidth  /  requests . size () ; 

} 

synchronized  (requests . elementAt (i ) )  { 

bandwidth  +=  requests . get (i ). getBandwidth () ; 

//  Acquires  locks  in  increasing  order 

return  calculateAverageBandwidth (t+i ,  bandwidth); 


private  double  calculateAverageResponseTime (int  i,  long  responseTime)  { 
if  (i  <=  -1)  { 

return  responseTime  /  requests  .  size  ()  ; 

} 
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synchronized  (requests . elementAt (i) )  { 

responseTime  +=  requests . get (i) . getResponseTime () ; 

//  Acquires  locks  in  decreasing  order 

return  calculateAverageResponseTime (--i,  responseTime); 


The  monitoring  application  is  built  around  the  WebRequestAnalyzer  class  that  maintains  a  list 
of  web  requests  using  the  requests  vector  and  includes  the  addWebRequest  ( )  setter  method. 
Any  thread  can  request  the  average  bandwidth  or  average  response  time  of  all  web  requests  by 
invoking  the  getAverageBandwidth  ( )  and  getAverageResponseTime  ( )  methods. 

These  methods  use  fine-grained  locking  by  holding  locks  on  individual  elements  (web  requests) 
of  the  vector.  These  locks  permit  new  requests  to  be  added  while  the  computations  are  still  un¬ 
derway.  Consequently,  the  statistics  reported  by  the  methods  are  accurate  when  they  return  the 
results. 

Unfortunately,  this  noncompliant  code  example  is  prone  to  deadlock  because  the  recursive  calls 
within  the  synchronized  regions  of  these  methods  acquire  the  intrinsic  locks  in  opposite  numerical 
orders.  That  is,  calculateAverageBandwidth  ( )  requests  locks  from  index  0  up  to 
requests  .  size  ( )  -  1,  whereas  calculateAverageResponseTime  ( )  requests  them  from 
index  requests  .  size  ( )  -  1  down  to  0.  Because  of  recursion,  no  previously  acquired  locks  are 
released  by  either  method.  Deadlock  occurs  when  two  threads  call  these  methods  out  of  order, 
because  one  thread  calls  calculateAverageBandwidth  ( ) ,  while  the  other  calls 
calculateAverageResponseTime  ( )  before  either  method  has  finished  executing. 

For  example,  if  there  are  20  requests  in  the  vector  and  one  thread  calls 

getAverageBandwidth  ( ) ,  the  thread  acquires  the  intrinsic  lock  of  WebRequest  0,  the  first 
element  in  the  vector.  Meanwhile,  if  a  second  thread  calls  getAverageResponseTime  ( ) ,  it 
acquires  the  intrinsic  lock  of  web  request  19,  the  last  element  in  the  vector.  Consequently,  dead¬ 
lock  results  because  neither  thread  can  acquire  all  of  the  locks  and  proceed  with  the  calculations. 

Note  that  the  addWebRequest  ( )  method  also  has  a  race  condition  with 

calculateAverageResponseTime  ( ) .  While  iterating  over  the  vector,  new  elements  can  be 
added  to  the  vector,  invalidating  the  results  of  the  previous  computation.  This  race  condition  can 
be  prevented  by  locking  on  the  last  element  of  the  vector  (when  it  contains  at  least  one  element) 
before  inserting  the  element. 
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3.8.6  Compliant  Solution 


In  this  compliant  solution,  the  two  calculation  methods  acquire  and  release  locks  in  the  same  or¬ 
der,  beginning  with  the  first  web  request  in  the  vector. 


public  final  class  WebRequestAnalyzer  { 

private  final  Vector<WebRequest>  requests  =  new  Vector<WebRequest> ( ) ; 


public  boolean  addWebRequest (WebRequest  request)  { 

return  requests . add (new  WebRequest (request . getBandwidth () , 
request . getResponseTime ( ) ) ) ; 


public  double  getAverageBandwidth ( )  { 

if  (requests . size ( )  ==  0)  { 

throw  new  IllegalStateException ( "The  vector  is  empty!"); 

} 

return  calculateAverageBandwidth ( 0 ,  0) ; 


public  double  getAverageResponseTime ( )  { 
if  (requests . size  ( )  ==  0)  { 

throw  new  IllegalStateException ("The  vector  is  empty!"); 

| 

return  calculateAverageResponseTime (0,  0); 


private  double  calculateAverageBandwidth (int  i,  long  bandwidth)  { 
if  (i  ==  requests  .  size  ()  )  { 

return  bandwidth  /  requests . size ()  ; 

} 

synchronized  (requests . elementAt (i ) )  {  //  Acquires  locks  in  increasing  order 

bandwidth  +=  requests . get (i ). getBandwidth () ; 
return  calculateAverageBandwidth (++i ,  bandwidth); 


private  double  calculateAverageResponseTime (int  i,  long  responseTime)  { 
if  (i  ==  requests  .  size  ()  )  { 

return  responseTime  /  requests . size () ; 

synchronized  (requests . elementAt (i ) )  { 

responseTime  +=  requests . get (i) . getResponseTime () ; 

//  Acquires  locks  in  increasing  order 

return  calculateAverageResponseTime (++i ,  responseTime); 


} 
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Consequently,  while  one  thread  is  calculating  the  average  bandwidth  or  response  time,  another 
thread  cannot  interfere  or  induce  deadlock.  That  is  because  the  other  thread  first  needs  to  syn¬ 
chronize  on  the  first  web  request,  which  cannot  happen  before  the  first  calculation  completes. 

There  is  no  need  to  lock  on  the  last  element  of  the  vector  in  addWebRequest  ( )  for  two  reasons: 
(1)  because  locks  are  acquired  in  increasing  order  in  all  the  methods  and  (2)  because  updates  to 
the  vector  are  reflected  in  the  results  of  the  computations. 


3.8.7  Risk  Assessment 

Acquiring  and  releasing  locks  in  the  wrong  order  can  result  in  deadlock. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK07-  J 

low 

likely 

high 

P3 

L3 
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3.9  LCK08-J.  Ensure  actively  held  locks  are  released  on  exceptional  conditions 

An  exceptional  condition  can  circumvent  the  release  of  a  lock,  leading  to  deadlock.  According  to 
the  Java  API  [Sun  2009b] 

A  ReentrantLock  is  owned  by  the  thread  last  successfully  locking,  but  not  yet  unlocking 
it.  A  thread  invoking  lock  will  return,  successfully  acquiring  the  lock,  when  the  lock  is  not 
owned  by  another  thread. 

Consequently,  an  unreleased  lock  in  any  thread  will  stop  other  threads  from  acquiring  the  same 
lock.  Intrinsic  locks  of  class  objects  used  for  method  and  block  synchronization  are  automatically 
released  on  exceptional  conditions  (such  as  abnormal  thread  termination). 

3.9.1  Noncompliant  Code  Example  (Checked  Exception) 

This  noncompliant  code  example  protects  a  resource  using  a  ReentrantLock  but  fails  to  release 
the  lock  if  an  exception  occurs  while  performing  operations  on  the  open  file.  If  an  exception  is 
thrown,  control  transfers  to  the  catch  block,  and  the  call  to  unlock  ( )  is  not  executed. 

public  final  class  Client  { 

public  void  doSomething (File  file)  { 
final  Lock  lock  =  new  ReentrantLock () ; 
try  { 

lock. lock ( )  ; 

InputStream  in  =  new  FilelnputStream (f ile) ; 

//  Perform  operations  on  the  open  file 
lock . unlock ( ) ; 

}  catch  (FileNotFoundException  fnf)  { 

//  Handle  the  exception 

} 

} 

} 

Note  that  the  lock  is  not  released,  even  when  the  doSomething  ( )  method  returns. 

This  noncompliant  code  example  does  not  close  the  input  stream  and,  consequently,  also  violates 
guideline  “FIO06-J.  Ensure  all  resources  are  properly  closed  when  they  are  no  longer  needed.”5 

3.9.2  Compliant  Solution  (finally  Block) 

This  compliant  solution  encapsulates  operations  that  may  throw  an  exception  in  a  try  block  im¬ 
mediately  after  acquiring  the  lock.  The  lock  is  acquired  just  before  the  try  block,  which  guaran¬ 
tees  that  the  lock  is  held  when  the  finally  block  executes.  Invoking  Lock .  unlock  ( )  in  the 
finally  block  ensures  that  the  lock  is  released,  regardless  of  whether  an  exception  occurred. 

public  final  class  Client  { 

public  void  doSomething (File  file)  { 
final  Lock  lock  =  new  ReentrantLock (); 


This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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InputStream  in  =  null; 
lock. lock  ( ) ; 
try  { 

in  =  new  FilelnputStream (file) ; 

//  Perform  operations  on  the  open  file 
}  catch (FileNotFoundException  fnf)  { 

//  Forward  to  handler 
}  finally  { 

lock . unlock ( ) ; 

if (in  ! =  null)  { 
try  { 

in . close  ( ) ; 

}  catch  (IOException  e)  { 

//  Forward  to  handler 

1 

I 

| 

} 

3.9.3  Compliant  Solution  (Execute-Around  Idiom) 

The  execute-around  idiom  provides  a  generic  mechanism  for  performing  resource  allocation  and 
clean-up  operations  so  that  the  client  can  focus  on  specifying  only  the  required  functionality.  This 
idiom  reduces  clutter  in  client  code  and  provides  a  secure  mechanism  for  resource  management. 

In  this  compliant  solution,  the  client’s  doSomething  ( )  method  provides  only  the  required  func¬ 
tionality  by  implementing  the  doSomethingWithFile  ( )  method  of  the  LockAction  inter¬ 
face,  without  having  to  manage  the  acquisition  and  release  of  locks  or  the  open  and  close  opera¬ 
tions  of  files.  The  ReentrantLockAction  class  encapsulates  all  resource  management  actions. 

public  interface  LockAction  { 

void  doSomethingWithFile ( InputStream  in); 

} 

public  final  class  ReentrantLockAction  { 

public  static  void  doSomething (File  file,  LockAction  action)  { 

Lock  lock  =  new  ReentrantLock ( ) ; 

InputStream  in  =  null; 
lock. lock ( ) ; 
try  { 

in  =  new  FilelnputStream ( file) ; 
action . doSomethingWithFile (in) ; 

}  catch  (FileNotFoundException  fnf)  { 

//  Forward  to  handler 
}  finally  { 

lock . unlock ( ) ; 


CMU/SEI-2010-TR-015  |  74 


LCK08-J 


if  (in  !=  null)  { 
try  { 

in . close  ( ) ; 

}  catch  (IOException  e)  { 

//  Forward  to  handler 

1 

| 

l 

} 

} 

public  final  class  Client  { 

public  void  doSomething (File  file)  { 

ReentrantLockAction . doSomething (file,  new  LockAction()  { 
public  void  doSomethingWithFile ( InputStream  in)  { 

//  Perform  operations  on  the  open  file 

} 

})  ; 

} 

1 

3.9.4  Noncompliant  Code  Example  (Unchecked  Exception) 

This  noncompliant  code  example  uses  a  ReentrantLock  to  protect  a  java .  util .  Date  in¬ 
stance,  which  is  not  thread-safe  by  design.  The  doSomethingSafely  ( )  method  must  catch 
Throwable  to  comply  with  guideline  “EXC06-J.  Do  not  allow  exceptions  to  transmit  sensitive 
information.”6 

final  class  DateHandler  { 

private  final  Date  date  =  new  DateO; 
final  Lock  lock  =  new  ReentrantLock () ; 
public  void  doSomethingSafely (String  str)  { 
try  { 

doSomething (str) ; 

}  catch (Throwable  t)  { 

//  Forward  to  handler 

} 

1 

public  void  doSomething (String  str)  { 
lock. lock ( ) ; 

String  datestring  =  date . toString ( ) ; 
if  (str. equals (datestring) )  { 

II  ... 

} 

lock . unlock ( ) ; 


This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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Because  the  doSomething  ( )  method  fails  to  check  if  str  is  null,  a  runtime  exception  can  oc¬ 
cur,  preventing  the  lock  from  being  released. 

3.9.5  Compliant  Solution  (finally  Block) 

This  compliant  solution  encapsulates  all  operations  that  can  throw  an  exception  in  a  try  block 
and  releases  the  lock  in  the  associated  finally  block. 

final  class  DateHandler  { 

private  final  Date  date  =  new  Date(); 
final  Lock  lock  =  new  ReentrantLock () ; 

public  void  doSomethingSafely (String  str)  { 
try  { 

doSomething (str) ; 

}  catch (Throwable  t)  { 

//  Forward  to  handler 

} 

| 

public  void  doSomething (String  str)  { 
lock. lock ( ) ; 
try  { 

String  datestring  =  date . toString ( ) ; 
if  (str  !=  null  &&  str . equals (datestring) )  { 

//  ... 

} 

}  finally  { 

lock . unlock ( ) ; 

} 

I 

} 

Consequently,  the  lock  is  released  even  in  the  event  of  a  runtime  exception.  The 
doSomething  ( )  method  also  ensures  that  the  string  is  not  null  to  avoid  throwing  a 

Null Pointer Except ion. 

3.9.6  Risk  Assessment 

Failing  to  release  locks  on  exceptional  conditions  may  lead  to  thread  starvation  and  deadlock. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK08-  J 

low 

likely 

low 

P9 

L2 
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3.10  LCK09-J.  Do  not  perform  operations  that  may  block  while  holding  a  lock 

Holding  locks  while  performing  time-consuming  or  blocking  operations  can  severely  degrade 
system  performance  and  result  in  starvation.  Furthermore,  deadlock  can  result  if  interdependent 
threads  block  indefinitely.  Blocking  operations  include  network,  file,  and  console  I/O  (for  exam¬ 
ple,  Console .  readLine  ( ) )  and  object  serialization.  Deferring  a  thread  indefinitely  also  consti¬ 
tutes  a  blocking  operation. 

If  the  JVM  interacts  with  a  file  system  that  operates  over  an  unreliable  network,  file  I/O  might 
incur  a  large  performance  penalty.  In  such  cases,  avoid  file  I/O  over  the  network  when  holding  a 
lock.  File  operations  (such  as  logging)  that  may  block  waiting  for  the  output  stream  lock  or  for 
I/O  to  complete  may  be  performed  in  a  dedicated  thread  to  speed  up  task  processing.  Logging 
requests  can  be  added  to  a  queue,  given  that  the  queue’s  put  ( )  operation  incurs  little  overhead  as 
compared  to  file  I/O  [Goetz  2006]. 

3.10.1  Noncompliant  Code  Example  (Deferring  a  Thread) 

This  noncompliant  code  example  defines  a  utility  method  that  accepts  a  time  argument. 

public  synchronized  void  doSomething (long  time) 
throws  InterruptedException  { 

II  ... 

Thread. sleep (time) ; 

1 


Because  the  method  is  synchronized,  if  the  thread  is  suspended,  other  threads  are  unable  to  use  the 
synchronized  methods  of  the  class.  The  current  object’s  monitor  is  not  released  because  the 
Thread .  sleep  ( )  method  does  not  have  any  synchronization  semantics,  as  detailed  in  guideline 
“THI00-J.  Do  not  assume  that  the  sleep  ( ) ,  yield  ( ) ,  or  getState  ()  methods  provide  syn¬ 
chronization  semantics”  on  page  9 1 . 

3.10.2  Compliant  Solution  (Intrinsic  Lock) 

This  compliant  solution  defines  the  doSomething  ( )  method  with  a  timeout  parameter  instead 
of  the  time  value.  Using  the  Ob  j  ect .  wait  ( )  rather  than  the  Thread .  sleep  ( )  method  al¬ 
lows  setting  a  timeout  period  during  which  a  notification  may  awaken  the  thread. 

public  synchronized  void  doSomething (long  timeout) 
throws  InterruptedException  { 

while  (Ccondition  does  not  hold>)  { 

wait (timeout) ;  //  Immediately  leaves  current  monitor 

} 

} 

The  current  object’s  monitor  is  released  immediately  upon  entering  the  wait  state.  After  the  time¬ 
out  period  has  elapsed,  the  thread  resumes  execution  after  reacquiring  the  current  object’s  moni¬ 
tor. 
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According  to  the  Java  API  class  Ob  j  ect  documentation  [Sun  2009b] 

Note  that  the  wait  method,  as  it  places  the  current  thread  into  the  wait  set  for  this  object, 
unlocks  only  this  object;  any  other  objects  on  which  the  current  thread  may  be  synchronized 
remain  locked  while  the  thread  waits.  This  method  should  only  be  called  by  a  thread  that  is 
the  owner  of  this  object's  monitor. 

Ensure  that  a  thread  that  holds  locks  on  other  objects  releases  them  appropriately,  before  entering 
the  wait  state.  Additional  guidance  on  waiting  and  notification  is  available  in  guidelines  “THI03- 
J.  Always  invoke  wait()  and  await()  methods  inside  a  loop”  on  page  101  and  “THI04-J.  Notify  all 
waiting  threads  instead  of  a  single  thread”  on  page  104. 

3.10.3  Noncompliant  Code  Example  (Network  I/O) 

This  noncompliant  code  example  shows  the  sendPage  ( )  method  that  sends  a  Page  object  from 
a  server  to  a  client.  The  method  is  synchronized  so  that  the  pageBuf  f  array  is  accessed  safely 
when  multiple  threads  request  concurrent  access. 

//  Class  Page  is  defined  separately.  It  stores  and  returns  the  Page  name  via  getNameO 
Page [ ]  pageBuf f  =  new  Page [MAX_PAGE_SIZE] ; 

public  synchronized  boolean  sendPage (Socket  socket.  String  pageName) 
throws  IOException  { 

//  Get  the  output  stream  to  write  the  Page  to 

ObjectOutputStream  out  =  new  Ob jectOutputStream (socket . getOutputStream ()) ; 

//  Find  the  Page  requested  by  the  client  (this  operation  requires  synchronization) 
Page  targetPage  =  null; 
for  (Page  p  ;  pageBuff)  { 

if  (p . getName  (). compareTo  (pageName)  ==  0)  { 
targetPage  =  p; 


//  Requested  Page  does  not  exist 
if  (targetPage  ==  null)  { 
return  false; 

# 

//  Send  the  Page  to  the  client  (does  not  require  any  synchronization) 
out.writeObject (targetPage) ; 

out . flush ( ) ; 
out . close  ( ) ; 
return  true; 

} 

Calling  writeOb  j  ect  ( )  within  the  synchronized  sendPage  ( )  method  can  result  in  delays  and 
deadlock-like  conditions  in  high-latency  networks  or  when  network  connections  are  inherently 
lossy. 
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3.10.4  Compliant  Solution 

This  compliant  solution  separates  the  process  into  a  sequence  of  steps: 

1 .  Perform  actions  on  data  structures  requiring  synchronization. 

2.  Create  copies  of  the  objects  to  be  sent. 

3 .  Perform  network  calls  in  a  separate  method  that  does  not  require  any  synchronization. 

In  this  compliant  solution,  the  synchronized  getPage  ( )  method  is  called  from  the  unsynchro¬ 
nized  sendPage  ( )  method  to  retrieve  the  requested  Page  in  the  pageBuf  f  array.  After  the 
Page  is  retrieved,  sendPage  ( )  calls  the  unsynchronized  deliverPage  ( )  method  to  deliver 
the  Page  to  the  client. 

public  boolean  sendPage (Socket  socket.  String  pageName)  {  //  No  synchronization 
Page  targetPage  =  getPage (pageName) ; 

if  (targetPage  ==  null) 
return  false; 

return  deliverPage  (socket,  targetPage); 

} 

private  synchronized  Page  getPage (String  pageName)  {  //  Requires  synchronization 
Page  targetPage  =  null; 

for  (Page  p  :  pageBuff)  { 

if  (p . getName  (). equals  (pageName)  )  { 
targetPage  =  p; 

} 

return  targetPage; 

} 

//  Return  false  if  an  error  occurs,  true  if  successful 
public  boolean  deliverPage (Socket  socket.  Page  page)  { 

ObjectOutputStream  out  =  null; 
boolean  result  =  true; 
try  { 

//  Get  the  output  stream  to  write  the  Page  to 

out  =  new  ObjectOutputStream (socket .getOutputStream () ) ; 

//  Send  the  Page  to  the  client 
out.writeObject (page) ; 

}  catch  (IOException  io)  { 
result  =  false; 

}  finally  { 

if  (out  !=  null)  { 
try  { 

out . flush ( ) ; 
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out . close  ( ) ; 

}  catch  (IOException  e)  { 
result  =  false; 

} 

} 

} 

return  result; 

} 

3.10.5  Exceptions 

LCK09-EX1:  Classes  that  provide  an  appropriate  termination  mechanism  to  callers  are  allowed 
to  violate  this  guideline  (see  guideline  ‘THI06-J.  Ensure  that  threads  and  tasks  perfonning  block¬ 
ing  operations  can  be  terminated”  on  page  1 14). 

LCK09-EX2:  A  method  that  requires  multiple  locks  may  hold  several  locks  while  waiting  for  the 
remaining  locks  to  become  available.  This  constitutes  a  valid  exception,  although  the  programmer 
must  follow  other  applicable  guidelines  to  avoid  deadlock.  See  guideline  “LCK07-J.  Avoid  dead¬ 
lock  by  requesting  and  releasing  locks  in  the  same  order”  on  page  63  for  more  information. 

3.10.6  Risk  Assessment 

Blocking  or  lengthy  operations  performed  within  synchronized  regions  may  result  in  a  deadlocked 
or  unresponsive  system. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK09-J 

low 

probable 

high 

P2 

L3 
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3.11  LCK10-J.  Do  not  use  incorrect  forms  of  the  double-checked  locking  idiom 

Instead  of  initializing  a  member  object  using  a  constructor,  lazy  initialization  can  be  used  to  defer 
the  construction  of  the  member  object  until  an  instance  is  actually  required.  Lazy  initialization 
also  helps  in  breaking  harmful  circularities  in  class  and  instance  initialization,  and  performing 
other  optimizations  [Bloch  2005a]. 

A  class  or  an  instance  method  is  used  for  lazy  initialization,  depending  on  whether  the  member 
object  is  static.  The  method  checks  whether  the  instance  has  already  been  created  and,  if  not, 
creates  it.  If  the  instance  already  exists,  it  simply  returns  it: 

//  Correct  single  threaded  version  using  lazy  initialization 
final  class  Foo  { 

private  Helper  helper  =  null; 

public  Helper  getHelper()  { 
if  (helper  ==  null)  { 
helper  =  new  Helper)); 

} 

return  helper; 

1 

II  ... 

} 


In  a  multithreaded  application,  initialization  must  be  synchronized  so  that  multiple  threads  do  not 
create  extraneous  instances  of  the  member  object: 

//  Correct  multithreaded  version  using  synchronization 
final  class  Foo  { 

private  Helper  helper  =  null; 

public  synchronized  Helper  getHelper()  { 
if  (helper  ==  null)  { 
helper  =  new  Helper (); 

} 

return  helper; 

} 

//  ... 

} 

The  double-checked  locking  idiom  improves  performance  by  limiting  synchronization  to  the  rare 
case  of  new  instance  creation  and  foregoing  it  during  the  common  case  of  retrieving  an  already 
created  instance. 

Incorrect  forms  of  the  double-checked  idiom  include  those  that  allow  an  uninitialized  or  partially 
initialized  object  to  be  published. 
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3.11.1  Noncompliant  Code  Example 

The  double-checked  locking  pattern  uses  block  synchronization  instead  of  method  synchroniza¬ 
tion  and  installs  an  additional  null  check  before  attempting  synchronization.  This  noncompliant 
code  example  uses  the  incorrect  form  of  the  double-checked  locking  idiom. 

//  "Double-Checked  Locking"  idiom 
final  class  Foo  { 

private  Helper  helper  =  null; 
public  Helper  getHelper()  { 
if  (helper  ==  null)  { 
synchronized  (this)  { 
if  (helper  ==  null)  { 
helper  =  new  Helper  (); 


} 

return  helper; 

} 

//  Other  methods  and  members... 

} 

According  to  Pugh  [Pugh  2004] 

.  .  .  writes  that  initialize  the  Helper  object  and  the  write  to  the  helper  field  can  be  done  or 
perceived  out  of  order.  As  a  result,  a  thread  which  invokes  getHelper  ( )  could  see  a  non¬ 
null  reference  to  a  helper  object,  but  see  the  default  values  for  fields  of  the  helper  object, 
rather  than  the  values  set  in  the  constructor. 

Even  if  the  compiler  does  not  reorder  those  writes,  on  a  multiprocessor  the  processor  or  the 
memory  system  may  reorder  those  writes,  as  perceived  by  a  thread  running  on  another  pro¬ 
cessor. 

Also  see  guideline  “TSM03-J.  Do  not  publish  partially  initialized  objects”  on  page  162. 

3.11.2  Compliant  Solution  (Volatile) 

This  compliant  solution  declares  the  helper  field  volatile. 

//  Works  with  acquire/release  semantics  for  volatile 
//  Broken  under  JDK  1.4  and  earlier 
final  class  Foo  { 

private  volatile  Helper  helper  =  null; 

public  Helper  getHelper ()  { 

if  (helper  ==  null)  { 
synchronized  (this)  { 
if  (helper  ==  null)  { 

helper  =  new  Helper ();  //  If  the  helper  is  null,  create  a  new  instance 

} 

} 
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} 

return  helper;  //  If  helper  is  non-null,  return  its  instance 

1 

} 

If  a  thread  initializes  the  Helper  object,  a  happens-before  relationship  is  established  between  this 
thread  and  another  that  retrieves  and  returns  the  instance  [Pugh  2004,  Manson  2004], 

3.11.3  Compliant  Solution  (Static  Initialization) 

This  compliant  solution  initializes  the  helper  field  in  the  declaration  of  the  static  variable.7 

final  class  Foo  { 

private  static  final  Helper  helper  =  new  Helper)); 

public  static  Helper  getHelperf)  { 
return  helper; 

} 

Variables  that  are  declared  static  and  initialized  at  declaration,  or  from  a  static  initializer,  are 
guaranteed  to  be  fully  constructed  before  being  made  visible  to  other  threads. 

3.11.4  Compliant  Solution  (Initialize-On-Demand,  Holder  Class  Idiom) 

This  compliant  solution  uses  the  initialize-on-demand,  holder  class  idiom  that  implicitly  incorpo¬ 
rates  lazy  initialization  by  declaring  a  static  variable  within  the  static  Holder  inner  class. 

final  class  Foo  { 

//  Lazy  initialization 
private  static  class  Holder  { 

static  Helper  helper  =  new  Helper))  ; 

1 

public  static  Helper  getlnstance  ( )  { 

return  Holder .helper ; 

1 

Initialization  of  the  static  helper  field  is  deferred  until  the  getlnstance  ( )  method  is  called. 
This  idiom  is  a  better  choice  than  the  double-checked,  locking  idiom  for  lazily  initializing  static 
fields  [Bloch  2008].  However,  this  idiom  cannot  be  used  to  lazily  initialize  instance  fields  [Bloch 
2001], 


7  The  Java  Memory  Model:  the  building  block  of  concurrency,  by  Jeremy  Manson.  Java  Developer  Connection 
Tech  Tips,  by  Glen  McCluskey,  April  10,  2001. 
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3.11.5  Compliant  Solution  (ThreadLocal  Storage) 

This  compliant  solution  (originally  suggested  by  Terekhov  [Pugh  2004])  uses  a  ThreadLocal 
object  to  lazily  create  a  Helper  instance. 

final  class  Foo  { 

private  final  ThreadLocal<Foo>  perThreadlnstance  =  new  ThreadLocal<Foo> ( ) ; 
private  Helper  helper  =  null; 

public  Helper  getHelperO  { 

if  (perThreadlnstance. get ()  ==  null)  { 
createHelper ( ) ; 

} 

return  helper; 

I 

private  synchronized  void  createHelper ( )  { 

if  (helper  ==  null)  { 
helper  =  new  Helper (); 

} 

//  Any  non-null  value  can  be  used  as  an  argument  to  set() 
perThreadlnstance . set (this) ; 

1 

} 

3.11.6  Compliant  Solution  (Immutable) 

In  this  compliant  solution,  the  Helper  class  is  immutable  and  consequently  guaranteed  to  be  ful¬ 
ly  constructed  before  becoming  visible.  In  this  case,  there  are  no  further  requirements  to  ensure 
that  the  double-checked  locking  idiom  does  not  result  in  the  publication  of  an  uninitialized  or  par¬ 
tially  initialized  field. 

public  final  class  Helper  { 
private  final  int  n; 

public  Helper  (int  n)  { 
this.n  =  n; 

} 

//  Other  fields  and  methods,  all  fields  are  final 

} 

final  class  Foo  { 

private  Helper  helper  =  null; 

public  Helper  getHelperO  { 
if  (helper  ==  null)  { 
synchronized  (this)  { 
if  (helper  ==  null)  { 
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helper  =  new  Helper (42);  //  If  the  helper  is  null,  create  a  new  instance 

} 

} 

f 

return  helper;  //  If  helper  is  non-null,  return  its  instance 

} 

} 

3.11.7  Exceptions 

LCK10-EX1:  The  noncompliant  form  of  the  double-checked  locking  idiom  can  be  used  for  32-bit 
primitive  values  (for  example,  int  or  float)  [Pugh  2004].  Note  that  it  does  not  work  for  values 
of  type  long  or  double  because  unsynchronized  reads/writes  of  64-bit  primitives  are  not  guar¬ 
anteed  to  be  atomic  (see  guideline  “VNA05-J.  Ensure  atomicity  when  reading  and  writing  64-bit 
values”  on  page  33). 

3.1 1 .8  Risk  Assessment 


Using  incorrect  forms  of  the  double-checked,  locking  idiom  can  lead  to  synchronization  prob¬ 
lems. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK10-  J 

low 

probable 

medium 

P4 

L3 

3.11.9  References 

[Bloch  2001] 

[Bloch  2008] 

[Gosling  2005] 

[MITRE  2010] 

[Pugh  2004] 

[Sun  2009b] 


Item  48:  “Synchronize  access  to  shared  mutable  data” 
Item  71:  “Use  lazy  initialization  judiciously” 

Section  12.4,  “Initialization  of  Classes  and  Interfaces” 
CWE  ID  609  “Double-Checked  Locking” 


CMU/SEI-2010-TR-015  |  85 


LCK11-J 


3.12  LCK11-J.  Avoid  client-side  locking  when  using  classes  that  do  not  commit  to 
their  locking  strategy 

According  to  Goetz  and  colleagues  [Goetz  2006] 

Client-side  locking  entails  guarding  client  code  that  uses  some  object  X  with  the  lockX  uses 
to  guard  its  own  state.  In  order  to  use  client-side  locking,  you  must  know  what  lockX  uses. 

While  client-side  locking  is  acceptable  if  the  thread-safe  class  commits  to  its  locking  strategy  and 
clearly  documents  it,  Goetz  and  colleagues  caution  against  its  misuse  [Goetz  2006] : 

If  extending  a  class  to  add  another  atomic  operation  is  fragile  because  it  distributes  the  lock¬ 
ing  code  for  a  class  over  multiple  classes  in  an  object  hierarchy,  client-side  locking  is  even 
more  fragile  because  it  entails  putting  locking  code  for  class  C  into  classes  that  are  totally 
unrelated  to  C.  Exercise  care  when  using  client-side  locking  on  classes  that  do  not  commit  to 
their  locking  strategy. 

The  documentation  of  a  class  that  supports  client-side  locking  should  explicitly  state  its  applica¬ 
bility.  For  example,  the  j  ava  .  util .  concurrent .  ConcurrentHashMap<K,  V>  class  should 
not  be  used  for  client-side  locking  because  its  documentation  states  [Sun  2009b] 

.  .  .  even  though  all  operations  are  thread-safe,  retrieval  operations  do  not  entail  locking, 
and  there  is  not  any  support  for  locking  the  entire  table  in  a  way  that  prevents  all  access. 

This  class  is  fully  interoperable  with  Hashtable  in  programs  that  rely  on  its  thread  safety 
but  not  on  its  synchronization  details. 

In  general,  use  client-side  locking  only  when  the  documentation  of  the  class  recommends  it.  For 
example,  the  documentation  of  the  synchronizedList  ( )  wrapper  method  of  the 
java . util . Collections  class  states  [Sun  2009b] 

In  order  to  guarantee  serial  access,  it  is  critical  that  all  access  to  the  backing  list  is  accom¬ 
plished  through  the  returned  list.  It  is  imperative  that  the  user  manually  synchronize  on  the 
returned  list  when  iterating  over  it.  Failure  to  follow  this  advice  may  result  in  non- 
deterministic  behavior. 

When  the  backing  list  is  inaccessible  to  an  untrusted  client,  note  that  this  advice  is  consistent  with 
guideline  “LCK04-J.  Do  not  synchronize  on  a  collection  view  if  the  backing  collection  is  accessi¬ 
ble”  on  page  57. 

3.12.1  Noncompliant  Code  Example  (Intrinsic  Lock) 

This  noncompliant  code  example  uses  the  thread-safe  Book  class  that  cannot  be  refactored.  Re¬ 
factoring  might  be  impossible,  for  example,  if  the  source  code  is  not  available  for  review  or  the 
class  is  part  of  a  general  library  that  cannot  be  extended. 


final  class  Book  { 

//  May  change  its  locking  policy  in  the  future  to  use  private  final  locks 
private  final  String  title; 
private  Calendar  datelssued; 
private  Calendar  dateDue; 

Book (String  title)  { 
this. title  =  title; 
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} 

public  synchronized  void  issue (int  days)  { 
datelssued  =  Calendar . getlnstance () ; 
dateDue  =  Calendar .getlnstance () ; 
dateDue . add (datelssued. DATE,  days) ; 

} 


public  synchronized  Calendar  getDueDateO  { 
return  dateDue; 

} 


This  class  does  not  commit  to  its  locking  strategy  (that  is,  it  reserves  the  right  to  change  its  lock¬ 
ing  strategy  without  notice).  Furthermore,  it  does  not  document  that  callers  can  use  client-side 
locking  safely.  The  BookWrapper  client  class  uses  client-side  locking  in  the  renew  ( )  method 
by  synchronizing  on  a  Book  instance. 

//  Client 

public  class  BookWrapper  { 
private  final  Book  book; 

BookWrapper (Book  book)  { 
this. book  =  book; 

1 

public  void  issue (int  days)  { 
book. issue (days) ; 

} 

public  Calendar  getDueDateO  { 
return  book . getDueDate ( ) ; 

1 

public  void  renew ()  { 

synchronized (book)  { 

if  (book. getDueDate  ()  .before  (Calendar. getlnstance  ()  )  )  { 
throw  new  IllegalStateException ( "Book  overdue") ; 

}  else  { 

book. issue (14 ) ;  //  Issue  book  for  14  days 

} 

} 

} 

1 

If  the  Book  class  changes  its  synchronization  policy  in  the  future,  the  BookWrapper  class’s 
locking  strategy  might  silently  break.  For  instance,  the  BookWrapper  class’s  locking  strategy 
breaks  if  Book  is  modified  to  use  a  private  final  lock  object,  as  recommended  by  guideline 
“LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that  may  interact  with  untrusted 
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code”  on  page  41.  The  BookWrapper  class’s  locking  strategy  breaks  because  threads  that  call 
BookWrapper .  getDueDate  ( )  may  perform  operations  on  the  thread-safe  Book  using  its  new 
locking  policy.  However,  threads  that  call  the  renew  ( )  method  will  always  synchronize  on  the 
intrinsic  lock  of  the  Book  instance.  Consequently,  the  implementation  will  use  two  different 
locks. 

3.12.2  Compliant  Solution  (Private  Final  Lock  Object) 

This  compliant  solution  uses  a  private  final  lock  object  and  synchronizes  the  methods  of  the 
BookWrapper  class  using  this  lock. 

public  final  class  BookWrapper  { 
private  final  Book  book; 

private  final  Object  lock  =  new  Object (); 

BookWrapper (Book  book)  { 
this. book  =  book; 

} 

public  void  issue (int  days)  { 
synchronized (lock)  { 
book. issue (days) ; 

} 

1 

public  Calendar  getDueDate ()  { 

synchronized (lock)  { 

return  book . getDueDate () ; 

1 

} 

public  void  renew ()  { 

synchronized (lock)  { 

if  (book. getDueDate  ()  .before  (Calendar. getlnstance  ()  )  )  { 
throw  new  IllegalStateException ( "Book  overdue"); 

}  else  { 

book. issue (14 ) ;  //  Issue  book  for  14  days 

} 

1 

1 

} 

The  BookWrapper  class’s  locking  strategy  is  now  independent  of  the  locking  policy  of  the  Book 
instance. 

3.12.3  Noncompliant  Code  Example  (Class  Extension  and  Accessible  Member  Lock) 

Goetz  and  colleagues  describe  the  fragility  of  class  extension  for  adding  functionality  to  thread- 
safe  classes  [Goetz  2006]: 
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Extension  is  more  fragile  than  adding  code  directly  to  a  class,  because  the  implementation  of 
the  synchronization  policy  is  now  distributed  over  multiple,  separately  maintained  source 
files.  If  the  underlying  class  were  to  change  its  synchronization  policy  by  choosing  a  differ¬ 
ent  lock  to  guard  its  state  variables,  the  subclass  would  subtly  and  silently  break,  because  it 
no  longer  used  the  right  lock  to  control  concurrent  access  to  the  base  class ’s  state. 

In  this  noncompliant  code  example,  the  PrintablelPAddressList  class  extends  the 
thread-safe  IPAddressList  class.  PrintablelPAddressList  locks  on 
IPAddressList .  ips  in  the  addAndPrintIPAddresses  ( )  method.  This  is  another  example 
of  client-side  locking  because  a  subclass  is  using  an  object  owned  and  locked  by  its  superclass. 

//  This  class  may  change  its  locking  policy  in  the  future,  for  example, 

//  if  new  non-atomic  methods  are  added 
class  IPAddressList  { 

private  final  List<InetAddress>  ips  = 

Collections . synchronizedList (new  ArrayList<InetAddress> ( ) ) ; 

public  List<InetAddress>  getListO  { 

return  ips;  //  No  defensive  copies  required  as  package-private  visibility 

} 

public  void  addIPAddress (InetAddress  address)  { 
ips . add (address) ; 

} 

} 

class  PrintablelPAddressList  extends  IPAddressList  { 

public  void  addAndPrintIPAddresses (InetAddress  address)  { 
synchronized (getList () )  { 
addIPAddress (address) ; 

InetAddress!]  ia  =  (InetAddress [] )  getList (). toArray (new  InetAddress [0] ) ; 

//  ... 


If  the  IPAddressList  class  is  modified  to  use  block  synchronization  on  a  private  final  lock 
object  (as  recommended  by  guideline  “LCK00-J.  Use  private  final  lock  objects  to  synchronize 
classes  that  may  interact  with  untrusted  code”  on  page  41),  the  PrintablelPAddressList 
subclass  will  silently  break.  Moreover,  if  a  wrapper  such  as 

Collections  .  synchronizedList  ( )  is  used,  it  is  difficult  for  a  client  to  determine  the  type 
of  the  class  being  wrapped  in  order  to  extend  it  [Goetz  2006], 

3.12.4  Compliant  Solution  (Composition) 

This  compliant  solution  wraps  an  object  of  the  IPAddressList  class  and  provides  synchronized 
accessors  that  can  be  used  to  manipulate  the  state  of  the  object. 
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Composition  offers  encapsulation  benefits,  usually  with  minimal  overhead.  Refer  to  guideline 
“OBJ07-J.  Understand  how  a  superclass  can  affect  a  subclass  for  more  information  on  composi- 

j  •  ??  8 

tion. 

//  Class  IPAddressList  remains  unchanged 
class  PrintablelPAddressList  { 
private  final  IPAddressList  ips; 

public  PrintablelPAddressList ( IPAddressList  list)  { 
this. ips  =  list; 

1 

public  synchronized  void  addIPAddress ( InetAddress  address)  { 
ips . addIPAddress (address) ; 

| 

public  synchronized  void  addAndPrintIPAddresses ( InetAddress  address)  { 
addIPAddress (address) ; 

InetAddress[]  ia  =  (InetAddress!])  ips . getList ( ) . toArray (new  InetAddress [0] ) ; 

II  ... 

| 

} 

In  this  case,  composition  allows  the  PrintablelPAddressList  class  to  use  its  own  intrinsic 
lock  independent  of  the  underlying  list  class’s  lock.  The  underlying  collection  does  not  need  to  be 
thread-safe  because  the  PrintablelPAddressList  wrapper  prevents  direct  access  to  its  me¬ 
thods  by  publishing  its  own  synchronized  equivalents.  This  approach  provides  consistent  locking 
even  if  the  underlying  class  changes  its  locking  policy  in  the  future  [Goetz  2006], 

3.12.5  Risk  Assessment 


Using  client-side  locking  when  the  thread-safe  class  does  not  commit  to  its  locking  strategy  can 
cause  data  inconsistencies  and  deadlock. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

LCK11- J 

low 

probable 

medium 

P4 

L3 
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4  Thread  APIs  (THI)  Guidelines 


4.1  THIOO-J.  Do  not  assume  that  the  sleep(),  yield(),  or  getState()  methods  provide 
synchronization  semantics 

According  to  Section  17.9,  “Sleep  and  Yield”  of  the  Java  Language  Specification  [Gosling  2005] 

It  is  important  to  note  that  neither  Thread,  sleep  nor  Thread,  yi el d  have  any  synchro¬ 
nization  semantics.  In  particular,  the  compiler  does  not  have  to  flush  writes  cached  in  regis¬ 
ters  out  to  shared  memory  before  a  call  to  Thread,  sleep  or  Thread,  yi  el  d,  nor  does 
the  compiler  have  to  reload  values  cached  in  registers  cifter  a  call  to  Thread,  sleep  or 
Thread .  yield. 

Incorrectly  assuming  that  thread  suspension  and  yielding  do  any  of  the  following  can  result  in 
unexpected  behavior: 

•  flush  the  cached  registers 

•  reload  any  values 

•  provide  any  happens-before  relationships  when  execution  resumes 

4.1.1  Noncompiiant  Code  Example  (sleep  () ) 

This  noncompiiant  code  example  attempts  to  use  a  non-volatile  Boolean  done  as  a  flag  to  termi¬ 
nate  the  execution  of  a  thread.  A  separate  thread  sets  done  to  true  by  calling  the  shutdown  ( ) 
method. 

final  class  ControlledStop  implements  Runnable  { 
private  boolean  done  =  false; 

@Override  public  void  run()  { 
while  ( ! done)  { 
try  { 

Thread. sleep (1000)  ; 

}  catch  (InterruptedException  e)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 

} 

} 

} 

public  void  shutdown))  { 
this. done  =  true; 

} 

} 

However,  the  compiler  is  free  to  read  the  field  this  .  done  once  and  reuse  the  cached  value  in 
each  execution  of  the  loop.  Consequently,  the  while  loop  might  not  terminate,  even  if  another 
thread  calls  the  shutdown  ( )  method  to  change  the  value  of  this  .  done  [Gosling  2005].  This 
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error  could  have  resulted  from  the  programmer  incorrectly  assuming  that  the  call  to 
Thread .  sleep  ( )  would  cause  cached  values  to  be  reloaded. 

4.1.2  Compliant  Solution  (Volatile  Flag) 

This  compliant  solution  declares  the  flag  volatile  to  ensure  that  updates  to  it  are  made  visible 
across  multiple  threads. 

final  class  ControlledStop  implements  Runnable  { 
private  volatile  boolean  done  =  false; 

//  ... 

} 

The  volatile  flag  establishes  a  happens-before  relationship  between  this  thread  and  any  other 
thread  that  sets  done. 

4.1.3  Compliant  Solution  (Thread .  interrupt  ( ) ) 

A  better  solution  for  methods  that  call  sleep  ( )  is  to  use  thread  interruption,  which  causes  the 
sleeping  thread  to  wake  up  immediately  and  handle  the  interruption. 

final  class  ControlledStop  implements  Runnable  { 

©Override  public  void  run()  { 
while  (! Thread. interrupted () )  { 
try  { 

Thread. sleep (1000)  ; 

}  catch  (InterruptedException  e)  { 

Thread. cur rentThread ( ) . interrupt ( ) ; 

} 

} 

} 

public  void  shutdown))  { 

Thread. currentThread ( ) . interrupt () ; 

1 

} 

4.1.4  Noncompliant  Code  Example  (getstate  ( ) ) 

This  noncompliant  code  example  starts  a  thread  in  the  doSomething  ( )  method.  The  thread 
supports  interruption  by  checking  the  volatile  flag  and  blocks  waiting  until  notified.  The  stop  ( ) 
method  notifies  the  thread  if  it  is  blocked  on  the  wait  and  sets  the  flag  to  true  so  that  the  thread 
can  terminate. 

public  class  Waiter  { 
private  Thread  thread; 
private  volatile  boolean  flag; 
private  final  Object  lock  =  new  Object)); 
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public  void  doSomething ( )  { 

thread  =  new  Thread (new  Runnable ()  { 

@Override  public  void  run()  { 
synchronized (lock)  { 
while  ( ! flag)  { 
try  { 

lock. wait  ()  ; 

II  ... 

}  catch  ( Inter ruptedException  e)  { 

/ /  Forward  to  handler 

} 

} 

} 

} 

}) ; 

thread. start ( ) ; 

} 

public  boolean  stopO  { 
if  (thread  !=  null)  { 

if  (thread. getState ( )  ==  Thread. State .WAITING)  { 
flag  =  true; 
synchronized  (lock)  { 
lock .  notif yAll  ()  ; 

} 

return  true; 

} 

} 

return  false; 

} 

} 

Unfortunately,  the  stop  ( )  method  incorrectly  uses  the  Thread .  getState  ( )  method  to  check 
whether  the  thread  is  blocked  and  has  not  terminated  before  delivering  the  notification.  Using  the 
Thread .  getState  ( )  method  for  synchronization  control  such  as  checking  whether  a  thread  is 
blocked  on  a  wait  is  inappropriate.  This  is  true  because  a  blocked  thread  is  not  always  required  to 
enter  the  WAITING  or  TIMED  WAITING  state  in  cases  where  the  JVM  implements  blocking  us¬ 
ing  spin-waiting  [Goetz  2006].  Because  the  thread  may  never  enter  the  WAITING  state,  the 
stop  ( )  method  may  not  terminate  the  thread. 
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4.1.5  Compliant  Solution 

This  compliant  solution  removes  the  check  for  determining  whether  the  thread  is  in  the  WAITING 
state.  This  check  is  unnecessary  because  invoking  notifyAll  ( )  on  a  thread  that  is  not  blocked 
on  a  wait  ( )  invocation  has  no  effect. 

public  class  Waiter  { 

//  ... 

public  boolean  stopO  { 
if  (thread  !=  null)  { 
flag  =  true; 
synchronized  (lock)  { 
lock . notifyAll () ; 

1 

return  true; 

} 

return  false; 

1 

1 

4.1.6  Risk  Assessment 


Relying  on  the  Thread  class’s  sleep  ( ) ,  yield  ( ) ,  and  getState  ( )  methods  for  synchroniza¬ 
tion  control  can  cause  unexpected  behavior. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

THI00-  J 

low 

probable 

medium 

P4 

L3 

4.1.7  References 

[Gosling  2005]  Section  17.9,  “Sleep  and  Yield” 
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4.2  THI01-J.  Do  not  invoke  ThreadGroup  methods 

Each  thread  in  Java  is  assigned  to  a  thread  group  upon  the  thread’s  creation.  These  groups  are  im¬ 
plemented  by  the  j  ava .  lang .  ThreadGroup  class.  If  the  thread  group  name  is  not  specified 
explicitly,  the  main  default  group  is  assigned  by  the  JVM  [Sun  2008a].  The  convenience  methods 
of  the  ThreadGroup  class  can  be  used  to  operate  on  all  threads  belonging  to  a  thread  group  at 
once.  For  example,  the  ThreadGroup .  interrupt  ( )  method  interrupts  all  threads  in  the 
thread  group.  Thread  groups  also  help  reinforce  layered  security  by  confining  threads  into  groups 
so  that  they  do  not  interfere  with  threads  in  other  groups  [Oaks  2004], 

Even  though  thread  groups  are  useful  for  keeping  threads  organized,  programmers  seldom  benefit 
from  their  use  because  many  of  the  ThreadGroup  class  methods  are  deprecated  (for  example, 
allowThreadSuspension  ( ) ,  resume  ( ) ,  stop  ( ) ,  and  suspend  ( )  ).  Furthermore,  many 
non-deprecated  methods  are  obsolete  in  that  they  offer  little  desirable  functionality.  Ironically,  a 
few  ThreadGroup  methods  are  not  even  thread-safe  [Bloch  2001], 

The  insecure  yet  non-deprecated  methods  include 

•  ThreadGroup . activeCount  ( ) 

According  to  the  Java  API,  the  activeCount  ( )  method  [Sun  2009b] 

Returns  an  estimate  of  the  number  of  active  threads  in  this  thread  group 

This  method  is  often  used  as  a  precursor  to  thread  enumeration.  If  a  thread  is  not  started,  it 
continues  to  reside  in  the  thread  group  and  is  considered  to  be  active.  Furthermore,  the  active 
count  is  affected  by  the  presence  of  certain  system  threads  [Sun  2009b].  Consequently,  the 
activeCount()  method  may  not  reflect  the  actual  number  of  running  tasks  in  the  thread  group. 

•  ThreadGroup . enumerate ( ) 

According  to  the  Java  API,  ThreadGroup  class  documentation  [Sun  2009b] 

[The  enumerate  ()  method]  Copies  into  the  specified  array  every  active  thread  in  this 
thread  group  and  its  subgroups.  An  application  should  use  the  activeCount  method  to 
get  an  estimate  of  how  big  the  array  should  be.  If  the  array  is  too  short  to  hold  all  the 
threads,  the  extra  threads  are  silently  ignored. 

Using  the  ThreadGroup  APIs  to  shut  down  threads  also  has  pitfalls.  Because  the  stop  ( )  me¬ 
thod  is  deprecated,  alternative  ways  are  required  to  stop  threads.  According  to  the  Java  Program¬ 
ming  Language  [Arnold  2006] 

One  way  is  for  the  thread  initiating  the  termination  to  join  the  other  threads  and  so  know 
when  those  threads  have  terminated.  However,  an  application  may  have  to  maintain  its  own 
list  of  the  threads  it  creates  because  simply  inspecting  the  ThreadGroup  may  return  library 
threads  that  do  not  terminate  and  for  which  join  will  not  return. 

The  Executor  framework  provides  a  better  API  for  managing  a  logical  grouping  of  threads  and 
offers  secure  facilities  for  handling  shutdown  and  thread  exceptions  [Bloch  2008]. 

4.2.1  Noncompliant  Code  Example 

This  noncompliant  code  example  contains  a  NetworkHandler  class  that  maintains  a 
controller  thread.  This  thread  delegates  a  new  request  to  a  worker  thread.  To  demonstrate  the 
race  condition  in  this  example,  the  controller  thread  services  three  requests  by  starting  three 
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threads  in  succession  from  its  run  ( )  method.  All  threads  are  defined  to  belong  to  the  Chief 
thread  group. 

final  class  HandleRequest  implements  Runnable  { 
public  void  run()  { 

//  Do  something 

} 

.1 

public  final  class  NetworkHandler  implements  Runnable  { 
private  static  ThreadGroup  tg  =  new  ThreadGroup ("Chief") ; 

@Override  public  void  run()  { 


new 

Thread (tg,  new 

HandleRequest () , 

"threadl") 

. start ( ) ; 

// 

Start 

thread 

1 

new 

Thread (tg,  new 

HandleRequest () , 

"thread2") 

. start  ( ) ; 

// 

Start 

thread 

2 

new 

Thread (tg,  new 

HandleRequest () , 

"thread3" ) 

. start  ( ) ; 

// 

Start 

thread 

3 

public  static  void  printActiveCount (int  point)  { 

System. out .println ( "Active  Threads  in  Thread  Group  "  +  tg.getNameO  + 

"  at  point  ("  +  point  +  +  "  "  +  tg . activeCount ()) ; 

|j 

public  static  void  printEnumeratedThreads (Thread [ ]  ta,  int  len)  { 

System. out .println ( "Enumerating  all  threads..."); 
for (int  i  =  0;  i  <  len;  i++)  { 

System. out .println ( "Thread  "  +  i  +  "  =  "  +  ta[i] . getNameO); 

| 

} 

public  static  void  main (String [ ]  args)  throws  InterruptedException  { 

//  Start  thread  controller 

Thread  thread  =  new  Thread(tg,  new  NetworkHandler)),  "controller"); 
thread. start ( ) ; 

Thread!]  ta  =  new  Thread! tg. activeCount ()] ;  //  Gets  the  active  count  (insecure) 
printActiveCount ( 1 ) ;  //  PI 

Thread. sleep (1000) ;  //  Delay  to  demonstrate  TOCTOU  condition  (race  window) 

printActiveCount (2 ) ;  //  P2 :  the  thread  count  changes  as  new  threads  are  initiated 

//  Incorrectly  uses  the  (now  stale)  thread  count  obtained  at  PI 
int  n  =  tg. enumerate (ta) ; 

printEnumeratedThreads (ta,  n) ;  //  Silently  ignores  newly  initiated  threads 

//  (between  PI  and  P2) 

//  This  code  destroys  the  thread  group  if  it  does  not  have  any  alive  threads 
for  (Thread  thr  :  ta)  { 
thr . interrupt ( ) ; 
while (thr . isAlive ( ) ) ; 
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} 

tg. destroy ( )  ; 

} 

} 

There  is  a  time-of-check-to-time-of-use  (TOCTOU)  vulnerability  in  this  implementation  because 
obtaining  the  count  and  enumerating  the  list  do  not  constitute  an  atomic  operation.  If  new  requests 
occur  after  the  call  to  activeCount  ( )  and  before  the  call  to  enumerate  ( )  in  the  main  ( ) 
method,  the  total  number  of  threads  in  the  group  will  increase  but  the  enumerated  list  ta  will  con¬ 
tain  only  the  initial  number,  that  is,  two  thread  references  (main  and  controller).  Consequent¬ 
ly,  the  program  will  fail  to  account  for  the  newly  started  threads  in  the  Chief  thread  group. 

Any  subsequent  use  of  the  ta  array  is  insecure.  For  example,  calling  the  destroy  ( )  method  to 
destroy  the  thread  group  and  its  subgroups  will  not  work  as  expected.  The  precondition  to  calling 
destroy  ( )  is  that  the  thread  group  is  empty  with  no  executing  threads.  The  code  attempts  to 
accomplish  this  by  interrupting  every  thread  in  the  thread  group.  However,  when  the  destroy  ( ) 
method  is  called,  the  thread  group  is  not  empty,  which  causes  a 
j  ava  .  lang .  IllegalThreadStateException  to  be  thrown. 

4.2.2  Compliant  Solution 

This  compliant  solution  uses  a  fixed  thread  pool,  rather  than  a  ThreadGroup,  to  group  its  three 
tasks.  The  java .  util .  concurrent .  ExecutorService  interface  provides  methods  to  man¬ 
age  the  thread  pool.  Note  that  there  are  no  methods  for  finding  the  number  of  actively  executing 
threads  or  for  enumerating  through  them.  However,  the  logical  grouping  can  help  control  the  be¬ 
havior  of  the  group  as  a  whole.  For  instance,  all  threads  belonging  to  a  particular  thread  pool  can 
be  terminated  by  calling  the  shutdownPool  ( )  method. 

public  final  class  NetworkHandler  { 

private  final  ExecutorService  executor; 

NetworkHandler (int  poolSize)  { 

this . executor  =  Executors . newFixedThreadPool (poolSize) ; 

} 

public  void  startThreads ( )  { 
for (int  i  =  0;  i  <  3;  i++)  { 

executor . execute (new  HandleRequest ( ) ) ; 

} 

} 

public  void  shutdownPool ( )  { 
executor . shutdown ( ) ; 

} 
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public  static  void  main (String [ ]  args)  { 

NetworkHandler  nh  =  new  NetworkHandler (3) ; 
nh . startThreads ( ) ; 
nh . shutdownPool ( ) ; 

} 

} 

Before  Java  SE  5.0,  the  ThreadGroup  class  had  to  be  extended  because  there  was  no  other  di¬ 
rect  way  to  catch  an  uncaught  exception  in  a  separate  thread.  If  the  application  had  installed  an 
Uncaught  Except  ionHandler,  it  could  only  be  controlled  by  subclassing  ThreadGroup.  In 
recent  versions,  UncaughtExceptionHandler  is  maintained  on  a  per-thread  basis  using  an 
interface  enclosed  by  the  Thread  class,  which  leaves  little  to  no  functionality  for  the  Thread- 
Group  class  [Goetz  2006,  Bloch  2008]. 

Refer  to  guideline  “TPS03-J.  Ensure  that  tasks  executing  in  a  thread  pool  do  not  fail  silently”  on 
page  135  for  more  information  on  using  uncaught  exception  handlers  in  thread  pools. 

4.2.3  Risk  Assessment 


Using  the  ThreadGroup  APIs  may  result  in  race  conditions,  memory  leaks,  and  inconsistent 
object  state. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

THI01-  J 

low 

probable 

medium 

P4 

L3 
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4.3  THI02-J.  Do  not  invoke  Thread. run() 

It  is  critical  to  ensure  that  threads  are  started  correctly.  Thread  start-up  can  be  misleading  because 
sometimes  the  code  appears  to  be  performing  the  function  correctly,  when  it  is  actually  executing 
in  the  wrong  thread. 

The  Thread .  start  ( )  method  starts  executing  a  thread’s  run  ( )  method  in  the  respective 
thread.  It  is  a  mistake  to  directly  invoke  the  run  ( )  method  on  a  Thread  object.  When  invoked 
directly,  the  statements  in  the  run  ( )  method  execute  in  the  current  thread  instead  of  the  newly 
created  thread.  Furthermore,  if  the  Thread  object  is  not  constructed  from  a  Runnable  object  but 
rather  by  instantiating  a  subclass  of  Thread  that  does  not  override  the  run  ( )  method,  a  call  to 
the  subclass’s  run  ( )  method  invokes  Thread .  run  ( ) ,  which  does  nothing. 

4.3.1  Noncompliant  Code  Example 

This  noncompliant  code  example  explicitly  invokes  the  run  ( )  method  in  the  context  of  the  cur¬ 
rent  thread. 

public  final  class  Foo  implements  Runnable  { 

@Override  public  void  run()  { 

II  ... 

1 

public  static  void  main (String [ ]  args)  { 

Foo  foo  =  new  Foo(); 
new  Thread (foo)  . run  () ; 

| 

} 

The  start  ( )  method  is  not  invoked  on  the  new  thread  because  of  the  incorrect  assumption  that 
run  ( )  starts  the  new  thread.  Consequently,  the  statements  in  the  run  ( )  method  execute  in  the 
same  thread  instead  of  the  new  one. 

4.3.2  Compliant  Solution 

This  compliant  solution  correctly  uses  the  start  ( )  method  to  start  a  new  thread.  Then,  that  me¬ 
thod  internally  invokes  the  run  ( )  method  in  the  new  thread. 

public  final  class  Foo  implements  Runnable  { 

@Override  public  void  run()  { 

//  ... 

j 

public  static  void  main (String [ ]  args)  { 

Foo  foo  =  new  Foo(); 
new  Thread (foo) . start () ; 

1 

} 
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4.3.3  Exceptions 

THI02-EX1:  The  run  ( )  method  may  be  invoked  when  unit  testing  functionality.  Note  that  this 
method  cannot  be  used  to  test  a  class  for  multithreaded  use. 

Given  a  Thread  object  that  has  been  constructed  with  a  runnable  argument,  when  invoking  the 
Thread .  run  ( )  method,  the  Thread  object  may  be  cast  to  Runnable  to  eliminate  analyzer  di¬ 
agnostics. 

Thread  thread  =  new  Thread (new  Runnable ()  { 

@Override  public  void  run()  { 

//  ... 

} 

}) ; 

((Runnable)  thread)  . run  () ;  //  Exception:  This  does  not  start  a  new  thread 

Casting  a  thread  to  Runnable  before  calling  the  run  ( )  method  documents  that  the  explicit  call 
to  Thread .  run  ( )  is  intentional.  Adding  an  explanatory  comment  alongside  the  invocation  is 
highly  recommended. 

4.3.4  Risk  Assessment 

Failing  to  start  threads  correctly  can  cause  unexpected  behavior. 
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THI02-  J 

low 
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P4 

L3 
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4.4  THI03-J.  Always  invoke  wait()  and  await()  methods  inside  a  loop 

The  Ob  j  ect .  wait  ( )  method  temporarily  cedes  possession  of  a  lock  so  that  another  thread  that 
is  requesting  the  lock  can  proceed.  Ob  j  ect .  wait  ( )  must  always  be  called  from  a  synchronized 
block  or  method.  To  resume  the  waiting  thread,  the  requesting  thread  must  invoke  the  notify  ( ) 
method  to  notify  it.  Furthermore,  the  wait  ( )  method  should  be  invoked  in  a  loop  that  checks  if  a 
condition  predicate  holds.  Note  that  a  condition  predicate  is  the  negation  of  the  condition  expres¬ 
sion  in  the  loop.  For  example,  the  condition  predicate  for  removing  an  element  from  a  vector  is 
!  isEmpty  ( ) ,  whereas  the  condition  expression  for  the  while  loop  condition  is  isEmpty  ( ) .  The 
correct  way  to  invoke  the  wait  ( )  method  when  the  vector  is  empty  is  shown  below. 

public  void  consumeElement ( )  throws  InterruptedException  { 
synchronized  (vector)  { 

while  (vector . isEmpty () )  { 

vector .wait () ; 

} 


//  Consume  when  condition  holds 

} 

) 


The  notification  mechanism  notifies  the  waiting  thread  and  lets  it  check  its  condition  predicate. 
The  invocation  of  the  notify  ( )  or  notif  yAll  ( )  methods  in  another  thread  cannot  precisely 
determine  which  waiting  thread  is  resumed.  A  condition  predicate  statement  is  provided  so  that 
only  the  correct  thread  will  resume  upon  receiving  the  notification.  A  condition  predicate  also 
helps  when  a  thread  is  required  to  block  until  a  condition  becomes  true,  such  as  reading  data  from 
an  input  stream  before  proceeding. 

Safety  and  liveness  are  both  concerns  when  using  the  wait/notify  mechanism.  Safety  requires  all 
objects  to  maintain  consistent  states  in  a  multithreaded  environment  [Lea  2000a],  Liveness  re¬ 
quires  that  every  operation  or  method  invocation  execute  to  completion  without  interruption. 

To  guarantee  liveness,  the  while  loop  condition  must  be  tested  before  the  wait  ( )  method  is 
invoked.  This  is  done  in  case  another  thread  has  already  satisfied  the  condition  predicate  and  sent 
a  notification.  Invoking  the  wait  ( )  method  after  the  notification  has  been  sent  results  in  indefi¬ 
nite  blocking. 

To  guarantee  safety,  the  while  loop  condition  must  be  tested  even  after  the  wait  ( )  method  is 
invoked.  While  wait  ( )  is  meant  to  block  indefinitely  until  a  notification  is  received,  it  must  still 
be  encased  within  a  loop  to  prevent  the  following  vulnerabilities  [Bloch  2001]: 

•  thread  in  the  middle  -  A  third  thread  can  acquire  the  lock  on  the  shared  object  during  the  in¬ 
terval  between  a  notification  being  sent  and  the  receiving  thread  resuming  execution.  This 
thread  can  change  the  state  of  the  object,  leaving  it  inconsistent.  This  is  a  time-of-check-to- 
time-of-use  (TOCTOU)  condition. 

•  malicious  notification  -  There  is  no  guarantee  that  a  random  notification  will  not  be  received 
when  the  condition  predicate  is  false.  This  means  that  the  invocation  of  wait  ( )  may  be  nul¬ 
lified  by  the  notification. 
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•  misdelivered  notification  -  Sometimes  on  receipt  of  a  notif  yAll  ( )  signal,  an  unrelated 
thread  can  start  executing,  and  it  is  possible  for  its  condition  predicate  to  be  true.  Consequent¬ 
ly,  it  may  resume  execution  although  it  was  required  to  remain  dormant. 

•  spurious  wake-ups  -  Certain  JVM  implementations  are  vulnerable  to  spurious  wake-ups  that 
result  in  waiting  threads  waking  up  even  without  a  notification  [Sun  2009b], 

For  these  reasons,  the  condition  predicate  must  be  checked  after  the  wait  ( )  method  is  invoked. 
A  while  loop  is  the  best  choice  for  checking  the  condition  predicate  before  and  after  invoking 

wait  ( ) . 

Similarly,  the  await  ( )  method  of  the  Condition  interface  must  also  be  invoked  inside  a  loop. 
According  to  the  Java  API  [Sun  2009b],  Interface  Condition 

When  waiting  upon  a  Condition,  a  “spurious  wakeup”  is  permitted  to  occur,  in  general,  as  a 
concession  to  the  underlying  platform  semantics.  This  has  little  practical  impact  on  most  ap¬ 
plication  programs  as  a  Condition  should  always  be  waited  upon  in  a  loop,  testing  the  state 
predicate  that  is  being  waited  for.  An  implementation  is  free  to  remove  the  possibility  of  spu¬ 
rious  wakeups  but  it  is  recommended  that  applications  programmers  always  assume  that 
they  can  occur  and  so  always  wait  in  a  loop. 

New  code  should  use  the  j  ava .  util .  concurrent  concurrency  utilities  instead  of  the 
wait/notify  mechanism.  Flowever,  legacy  code  may  depend  on  the  wait/notify  mechanism. 

4.4.1  Noncompliant  Code  Example 

This  noncompliant  code  example  invokes  the  wait  ( )  method  inside  a  traditional  if  block  and 
fails  to  check  the  post-condition  after  the  notification  is  received.  If  the  notification  is  accidental 
or  malicious,  the  thread  can  wake  up  prematurely. 

synchronized  (object)  { 

if  (<condition  does  not  hold>)  { 
object. wait  ()  ; 

} 

//  Proceed  when  condition  holds 

} 


CMU/SEI-2010-TR-015  |  102 


THI03-J 


4.4.2  Compliant  Solution 

This  compliant  solution  calls  the  wait  ( )  method  from  within  a  while  loop  to  check  the  condi¬ 
tion  before  and  after  wait  ( )  is  called. 

synchronized  (object)  { 

while  (<condition  does  not  hold>)  { 
object. wait  ()  ; 

} 

//  Proceed  when  condition  holds 

} 

Similarly,  invocations  of  the  await  ( )  method  of  the 

j  ava  .  util .  concurrent .  locks  .  Condition  interface  must  be  enclosed  in  a  loop. 

4.4.3  Risk  Assessment 

To  guarantee  liveness  and  safety,  the  wait  ( )  and  await  ( )  methods  must  always  be  invoked 
inside  a  while  loop. 
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4.5  THI04-J.  Notify  all  waiting  threads  instead  of  a  single  thread 

A  thread  that  invokes  wait  ( )  expects  to  wake  up  and  resume  execution  when  its  condition  pre¬ 
dicate  becomes  true.  Waiting  threads  must  test  their  condition  predicates  upon  receiving  notifica¬ 
tions  and  resume  waiting  if  the  predicates  are  false,  to  be  compliant  with  guideline  “THI03-J.  Al¬ 
ways  invoke  wait()  and  awaitQ  methods  inside  a  loop”  on  page  101. 

The  notify  ( )  and  notifyAll  ( )  methods  of  the  j  ava .  lang .  Object  package  are  used  to 
wake  up  waiting  thread(s).  These  methods  must  be  invoked  from  code  that  holds  the  same  object 
lock  as  the  waiting  thread(s).  An  IllegalMonitorStateException  is  thrown  if  the  current 
thread  does  not  acquire  this  object’s  intrinsic  lock  before  invoking  these  methods.  The 
notifyAll  ( )  method  wakes  up  all  threads  and  allows  threads  whose  condition  predicate  is  true 
to  resume  execution.  Furthermore,  if  all  the  threads  whose  condition  predicate  evaluates  to  true 
previously  held  a  specific  lock  before  going  into  the  wait  state,  only  one  of  them  will  reacquire 
the  lock  upon  being  notified.  Presumably,  the  other  threads  will  resume  waiting.  The  notify  ( ) 
method  wakes  up  only  one  thread  and  makes  no  guarantees  as  to  which  thread  is  notified.  If  the 
thread’s  condition  predicate  doesn’t  allow  the  thread  to  proceed,  the  chosen  thread  may  resume 
waiting,  defeating  the  purpose  of  the  notification. 

The  notify  ( )  method  may  only  be  invoked  if  all  of  the  following  conditions  are  met: 

•  The  condition  predicate  is  identical  for  each  waiting  thread. 

•  All  threads  must  perform  the  same  set  of  operations  after  waking  up.  This  means  that  any  one 
thread  can  be  selected  to  wake  up  and  resume  for  a  single  invocation  of  notify  ( ) . 

•  Only  one  thread  is  required  to  wake  upon  the  notification. 

These  conditions  are  satisfied  by  threads  that  are  identical  and  provide  a  stateless  service  or 
utility. 

The  j  ava  .  util .  concurrent  utilities  (Condition  interface)  provide  the  signal  ( )  and 
signalAll  ( )  methods  to  awaken  threads  that  are  blocked  on  an  await  ( )  call.  Condition 
objects  are  required  when  using  Lock  objects.  A  Lock  object  allows  the  use  of  the  wait  ( )  and 
notify  ( )  methods.  However,  code  that  synchronizes  using  a  Lock  object  does  not  use  its  own 
intrinsic  lock.  Instead,  one  or  more  Condition  objects  are  associated  with  the  Lock  object. 
These  objects  interact  directly  with  the  locking  policy  enforced  by  the  Lock  object.  Consequent¬ 
ly,  the  Condition . await  ( ) , Condition . signal ( ) ,  and  Condition . signalAll ( )  me¬ 
thods  are  used  instead  of  Object  .wait  ( ) ,  Object .  notify  ( ) ,  and  Object .  notifyAll  ( ) . 

The  use  of  the  signal  ( )  method  is  insecure  when  multiple  threads  await  the  same  Condition 
object  unless  all  of  the  following  conditions  are  met: 

•  The  Condition  object  is  identical  for  each  waiting  thread. 

•  All  threads  must  perform  the  same  set  of  operations  after  waking  up.  This  means  that  any  one 
thread  can  be  selected  to  wake  up  and  resume  for  a  single  invocation  of  signal  () . 

•  Only  one  thread  is  required  to  wake  upon  receiving  the  signal. 

The  signal  ( )  method  may  also  be  invoked  when  both  of  the  following  conditions  are  met: 

•  Each  thread  uses  a  unique  Condition  object. 


CMU/SEI-2010-TR-015  |  104 


THI04-J 


•  Each  Condition  object  is  associated  with  a  common  Lock  object. 

The  signal  ( )  method,  if  used  securely,  has  better  performance  than  signalAll  ( ) . 

4.5.1  Noncompliant  Code  Example  (notify  ( ) ) 

This  noncompliant  code  example  shows  a  complex  multistep  process  being  undertaken  by  several 
threads.  Each  thread  executes  the  step  identified  by  the  time  field.  Each  thread  waits  for  the 
time  field  to  indicate  that  it  is  time  to  perform  the  corresponding  thread’s  step.  After  performing 
the  step,  each  thread  increments  time  and  then  notifies  the  thread  that  is  responsible  for  perform¬ 
ing  the  next  step. 

public  final  class  ProcessStep  implements  Runnable  { 
private  static  final  Object  lock  =  new  Object)); 
private  static  int  time  =  0; 

private  final  int  step;  //Do  operations  when  field  time  reaches  this  value 

public  ProcessStep (int  step)  { 
this. step  =  step; 

@Override  public  void  run()  { 
try  { 

synchronized  (lock)  { 
while  (time  !=  step)  { 
lock. wait  ()  ; 

} 

//  Perform  operations 
time+t; 

lock. notify ( ) ; 

1 

}  catch  ( Inter ruptedException  ie)  { 

Thread. currentThread (). interrupt () ;  //  Reset  interrupted  status 

} 

public  static  void  main (String [ ]  args)  { 
for  (int  i  =  4;  i  >=  0;  i--)  { 

new  Thread(new  ProcessStep (i) ). start () ; 

} 

f 

} 

This  noncompliant  code  example  violates  the  liveness  property.  Each  thread  has  a  different  condi¬ 
tion  predicate,  as  each  requires  step  to  have  a  different  value  before  proceeding.  The 
Ob j  ect .  notify  ( )  method  wakes  up  only  one  thread  at  a  time.  Unless  it  happens  to  wake  up 
the  thread  that  is  required  to  perform  the  next  step,  the  program  will  deadlock. 
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4.5.2  Compliant  Solution  (notif yAll  ( ) ) 

In  this  compliant  solution,  each  thread  completes  its  step  and  then  calls  notif  yAll  ( )  to  notify 
the  waiting  threads.  The  thread  that  is  ready  can  then  perform  its  task,  while  all  the  threads  whose 
condition  predicates  are  false  (loop  condition  expression  is  true)  promptly  resume  waiting. 

Only  the  run  ( )  method  from  the  noncomp liant  code  example  is  modified,  as  follows: 

SOverride  public  void  run()  { 
try  { 

synchronized  (lock)  { 
while  (time  !=  step)  { 
lock. wait  ()  ; 

} 

//  Perform  operations 
time++; 

lock,  notif  yAll  ()  ;  //  Use  notifyAllf)  instead  of  notify  () 

} 

}  catch  (InterruptedException  ie)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 

} 

} 

4.5.3  Noncompliant  Code  Example  (Condition  interface) 

This  noncompliant  code  example  is  similar  to  the  noncompliant  code  example  for  notify  ( )  but 
uses  the  Condition  interface  for  waiting  and  notification. 

public  class  ProcessStep  implements  Runnable  { 

private  static  final  Lock  lock  =  new  ReentrantLock ( ) ; 

private  static  final  Condition  condition  =  lock . newCondition ( ) ; 

private  static  int  time  =  0; 

private  final  int  step;  //Do  operations  when  field  time  reaches  this  value 

public  ProcessStep (int  step)  { 
this. step  =  step; 

} 

@Override  public  void  run()  { 
lock. lock  ( ) ; 
try  { 

while  (time  !=  step)  { 
condition . await ( ) ; 

} 

/ /  Perform  operations 
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time++; 

condition. signal ( ) ; 

}  catch  (InterruptedException  ie)  { 

Thread. currentThread (). interrupt () ;  //  Reset  interrupted  status 
}  finally  { 

lock . unlock ( ) ; 


public  static  void  main (String [ ]  args)  { 
for  (int  i  =  4;  i  >=  0;  i — )  { 

new  Thread(new  ProcessStep (i) ). start () ; 

} 

| 

} 

As  with  Ob j  ect .  notify  ( ) ,  the  signal  ( )  method  may  awaken  an  arbitrary  thread. 

4.5.4  Compliant  Solution  (signalAll  ( ) ) 

This  compliant  solution  uses  the  signalAll  ( )  method  to  notify  all  waiting  threads.  Before 
await  ( )  returns,  the  current  thread  reacquires  the  lock  associated  with  this  condition.  When  the 
thread  returns,  it  is  guaranteed  to  hold  this  lock  [Sun  2009b].  The  thread  that  is  ready  can  perform 
its  task,  while  all  the  threads  whose  condition  predicates  are  false  resume  waiting. 

Only  the  run  ( )  method  from  the  noncompliant  code  example  is  modified,  as  follows: 

©Override  public  void  run()  { 
lock. lock ( ) ; 
try  { 

while  (time  !=  step)  { 
condition . await ( ) ; 

} 

//  Perform  operations 
time++; 

condition . signalAll ( ) ; 

}  catch  (InterruptedException  ie)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 
}  finally  { 

lock . unlock ( ) ; 
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4.5.5  Compliant  Solution  (Unique  Condition  Per  Thread) 

This  compliant  solution  assigns  each  thread  its  own  condition.  All  the  Condition  objects  are 
accessible  to  all  the  threads. 

//  Declare  class  as  final  because  its  constructor  throws  an  exception 
public  final  class  ProcessStep  implements  Runnable  { 
private  static  final  Lock  lock  =  new  ReentrantLock ( ) ; 
private  static  int  time  =  0; 

private  final  int  step;  //  Do  operations  when  field  time  reaches  this  value 
private  static  final  int  MAX_STEPS  =  5; 

private  static  final  Condition!]  conditions  =  new  Condition [MAX_STEPS ] ; 

public  ProcessStep (int  step)  { 
if  (step  <=  MAX_STEPS)  { 
this. step  =  step; 

conditions [step]  =  lock . newCondition ( ) ; 

}  else  { 

throw  new  IllegalArgumentException ("Too  many  threads"); 


@Override  public  void  run()  { 
lock . lock ( ) ; 
try  { 

while  (time  !=  step)  { 

conditions [step] .await () ; 

} 

//  Perform  operations 
time+t; 

if  (step  +  1  <  conditions . length)  ( 
conditions [step  +  1], signal (); 

1 

}  catch  (InterruptedException  ie)  ( 

Thread. currentThread (). interrupt () ;  //  Reset  interrupted  status 
}  finally  { 

lock . unlock ( ) ; 


public  static  void  main  (String [ ]  args)  { 
for  (int  i  =  MAX_STEPS  -  1;  i  >=  0;  i — )  { 
ProcessStep  ps  =  new  ProcessStep  (i) ; 
new  Thread  (ps)  .  start  (); 
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Even  though  the  signal  ( )  method  is  used,  only  the  thread  whose  condition  predicate  corres¬ 
ponds  to  the  unique  Condition  variable  will  awaken. 

This  compliant  solution  is  safe  only  if  untrusted  code  cannot  create  a  thread  with  an  instance  of 
this  class. 


4.5.6  Risk  Assessment 

Notifying  a  single  thread  instead  of  all  waiting  threads  can  pose  a  threat  to  the  liveness  property  of 
the  system. 
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4.6  THI05-J.  Do  not  use  Thread.stop()  to  terminate  threads 

Threads  always  preserve  class  invariants  when  they  are  allowed  to  exit  normally.  Programmers 
often  try  to  terminate  threads  abruptly  when  they  believe  that  the  task  is  accomplished,  the  request 
has  been  canceled,  or  the  program  or  the  JVM  needs  to  shut  down  quickly. 

A  few  thread  APIs  were  introduced  to  facilitate  thread  suspension,  resumption,  and  termination 
but  were  later  deprecated  because  of  inherent  design  weaknesses.  For  example,  the 
Thread .  stop  ( )  method  causes  the  thread  to  immediately  throw  a  ThreadDeath  exception, 
which  usually  stops  the  thread. 

Invoking  Thread .  stop  ( )  results  in  the  release  of  all  the  locks  a  thread  has  acquired,  which 
may  corrupt  the  state  of  the  object.  The  thread  could  catch  the  ThreadDeath  exception  and  use  a 
finally  block  in  an  attempt  to  repair  the  inconsistent  object.  However,  that  requires  careful  in¬ 
spection  of  all  the  synchronized  methods  and  blocks  because  a  ThreadDeath  exception  can  be 
thrown  at  any  point  during  the  thread’s  execution.  Furthermore,  code  must  be  protected  from 
ThreadDeath  exceptions  that  may  result  when  executing  catch  or  finally  blocks  [Sun 
1999a], 

More  information  about  deprecated  methods  is  available  in  guideline  “MET15-J.  Do  not  use  de¬ 
precated  or  obsolete  methods.”9  Also,  refer  to  guideline  “EXC09-J.  Prevent  inadvertent  calls  to 
System .  exit  ( )  or  forced  shutdown”8  for  information  on  preventing  data  corruption  when  the 
JVM  is  shut  down  abruptly. 

4.6.1  Noncompliant  Code  Example  (Deprecated  Thread .  stop  ( ) ) 

This  noncompliant  code  example  shows  a  thread  that  fills  a  vector  with  pseudo-random  numbers. 
The  thread  is  forcefully  stopped  after  a  given  amount  of  time. 

public  final  class  Container  implements  Runnable  { 

private  final  Vector<Integer>  vector  =  new  Vector<Integer> ( 1000 ) ; 

public  Vector<Integer>  getVector()  { 
return  vector; 

} 

QOverride  public  synchronized  void  run()  { 

Random  number  =  new  Random ( 123L) ; 
int  i  =  vector . capacity () ; 
while  (i  >  0)  { 

vector . add (number . nextlnt ( 100 ) ) ; 
i  —  ; 

} 

} 

public  static  void  main (String [ ]  args)  throws  InterruptedException  { 

Thread  thread  =  new  Thread (new  Container ()) ; 

9  This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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thread. start ( ) ; 

Thread. sleep (5000) ; 
thread. stop ( ) ; 

} 

} 

Because  the  Vector  class  is  thread-safe,  operations  performed  by  multiple  threads  on  its  shared 
instance  are  expected  to  leave  it  in  a  consistent  state.  For  instance,  the  Vector .  size  ( )  method 
always  returns  the  correct  number  of  elements  in  the  vector  even  in  the  face  of  concurrent  changes 
to  the  vector.  This  is  because  the  vector  instance  uses  its  own  intrinsic  lock  to  prevent  other 
threads  from  accessing  it  while  its  state  is  temporarily  inconsistent. 

However,  the  Thread .  stop  ( )  method  causes  the  thread  to  stop  what  it  is  doing  and  throw  a 
ThreadDeath  exception.  All  acquired  locks  are  subsequently  released  [Sun  2009b].  If  the  thread 
is  in  the  process  of  adding  a  new  integer  to  the  vector  when  it  is  stopped,  the  vector  may  become 
accessible  while  it  is  in  an  inconsistent  state.  This  can  result  in  Vector .  size  ( )  returning  an 
incorrect  element  count,  for  example,  because  the  element  count  is  incremented  after  adding  the 
element. 

4.6.2  Compliant  Solution  (Volatile  Flag) 

This  compliant  solution  uses  a  volatile  flag  to  terminate  the  thread.  The  shutdown  ( )  accessor 
method  is  used  to  set  the  flag  to  true.  The  thread’s  run  ( )  method  polls  the  done  flag  and  termi¬ 
nates  when  it  becomes  true. 

public  final  class  Container  implements  Runnable  { 

private  final  Vector<Integer>  vector  =  new  Vector<Integer> ( 1000 ) ; 
private  volatile  boolean  done  =  false; 

public  Vector<Integer>  getVector()  { 
return  vector; 

} 

public  void  shutdown ()  { 

done  =  true; 

} 

SOverride  public  synchronized  void  run()  { 

Random  number  =  new  Random ( 123L) ; 
int  i  =  vector . capacity () ; 
while  ( ! done  &&  i  >  0)  { 

vector . add (number . nextlnt ( 100 ) ) ; 
i — ; 

} 

} 

public  static  void  main (String [ ]  args)  throws  InterruptedException  { 

Container  container  =  new  Container  (); 

Thread  thread  =  new  Thread (container); 
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thread. start ( )  ; 

Thread. sleep (5000)  ; 
container . shutdown ( ) ; 

} 

} 

4.6.3  Compliant  Solution  (Interruptible) 

In  this  compliant  solution,  the  Thread .  interrupt  ( )  method  is  called  from  main  ( )  to  termi¬ 
nate  the  thread.  Invoking  Thread .  interrupt  ( )  sets  an  internal  interrupt  status  flag.  The 
thread  polls  that  flag  using  the  Thread .  interrupted  ( )  method,  which  returns  true  if  the  cur¬ 
rent  thread  has  been  interrupted  and  clears  the  interrupt  status. 

public  final  class  Container  implements  Runnable  { 

private  final  Vector<Integer>  vector  =  new  Vector<Integer> (1000) ; 

public  Vector<Integer>  getVector()  { 
return  vector; 

} 

©Override  public  synchronized  void  run ()  { 

Random  number  =  new  Random ( 123L) ; 
int  i  =  vector . capacity () ; 
while  (! Thread. interrupted ( )  &&  i  >  0)  { 
vector . add (number . nextlnt  (100) ) ; 


public  static  void  main (String [ ]  args)  throws  InterruptedException  { 
Container  c  =  new  Container  (); 

Thread  thread  =  new  Thread (c); 
thread. start ( ) ; 

Thread. sleep (5000) ; 
thread. interrupt ( ) ; 

} 

} 


A  thread  may  use  interruption  for  performing  tasks  other  than  cancellation  and  shutdown.  Conse¬ 
quently,  a  thread  should  not  be  interrupted  unless  its  interruption  policy  is  known  in  advance. 
Failure  to  do  so  can  result  in  failed  interruption  requests. 
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4.6.4  Compliant  Solution  (Runtime  Permission  stopThread) 

Removing  the  default  j  ava  .  lang .  RuntimePermission  stopThread  permission  from  the 
security  policy  file  prevents  threads  from  being  stopped  using  the  Thread .  stop  ( )  method.  This 
approach  is  not  recommended  for  trusted,  custom-developed  code  that  uses  that  method  because 
the  existing  design  presumably  depends  on  the  ability  of  the  system  to  perform  this  action.  Fur¬ 
thermore,  the  system  may  not  be  designed  to  properly  handle  the  resulting  exception.  In  these  cas¬ 
es,  it  is  preferable  to  implement  an  alternate  design  approach  corresponding  to  another  compliant 
solution  described  in  this  guideline. 

4.6.5  Risk  Assessment 


Forcing  a  thread  to  stop  can  result  in  inconsistent  object  state.  Critical  resources  may  also  leak  if 
clean-up  operations  are  not  carried  out  as  required. 
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4.7  THI06-J.  Ensure  that  threads  and  tasks  performing  blocking  operations  can  be 
terminated 

Threads  and  tasks  that  block  on  operations  involving  network  or  file  input/output  (I/O)  must  pro¬ 
vide  callers  with  an  explicit  termination  mechanism  to  prevent  denial-of-service  vulnerabilities. 

4.7.1  Noncompliant  Code  Example  (Blocking  I/O,  Volatile  Flag) 

This  noncompliant  code  example  uses  a  volatile  done  flag  to  indicate  that  it  is  safe  to  shut  down 
the  thread,  as  suggested  in  guideline  “THI05-J.  Do  not  use  Thread .  stop  ( )  to  terminate 
threads”  on  page  110.  However,  setting  the  flag  does  not  terminate  the  thread  if  it  is  blocked  on 
network  I/O  as  a  consequence  of  invoking  the  readLine  ( )  method. 

public  final  class  SocketReader  implements  Runnable  {  //  Thread-safe  class 
private  final  Socket  socket; 
private  final  Buf f eredReader  in; 
private  volatile  boolean  done  =  false; 
private  final  Object  lock  =  new  Object)); 

public  SocketReader (String  host,  int  port)  throws  IOException  { 
this. socket  =  new  Socket (host,  port); 

this. in  =  new  Buf feredReader (new  InputStreamReader (this . socket . getlnputStream ())) ; 

} 

/ /  Only  one  thread  can  use  the  socket  at  a  particular  time 
@Override  public  void  run()  { 
try  { 

synchronized  (lock)  { 
readData  ( )  ; 

} 

}  catch  (IOException  ie)  { 

//  Forward  to  handler 


public  void  readData ()  throws  IOException  { 

String  string; 

while  ((done  &&  (string  =  in . readLine () )  !=  null)  { 

//  Blocks  until  end  of  stream  (null) 

| 

} 

public  void  shutdown))  { 
done  =  true; 

} 

public  static  void  main (String [ ]  args)  throws  IOException,  InterruptedException  { 
SocketReader  reader  =  new  SocketReader ("somehost",  25); 

Thread  thread  =  new  Thread (reader); 
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thread,  start  ()  ; 

Thread. sleep (1000) ; 

reader . shutdown () ;  //  Shutdown  the  thread 

} 

4.7.2  Noncompliant  Code  Example  (Blocking  I/O,  Interruptible) 

This  noncompliant  code  example  is  similar  to  the  preceding  one  but  uses  thread  interruption  to 
shut  down  the  thread.  Network  I/O  is  not  responsive  to  thread  interruption  when  a 
j  ava .  net .  Socket  is  being  used.  The  readData  ( )  and  main  ( )  methods  are  modified  as 
follows: 

public  final  class  SocketReader  implements  Runnable  {  //  Thread-safe  class 

U  ... 

public  void  readData ()  throws  IOException  { 

String  string; 

while  (! Thread. interrupted ( )  &&  (string  =  in . readLine ( ) )  !=  null)  { 

//  Blocks  until  end  of  stream  (null) 

} 

1 

public  static  void  main (String [ ]  args)  throws  IOException,  InterruptedException  { 
SocketReader  reader  =  new  SocketReader ("somehost",  25); 

Thread  thread  =  new  Thread (reader ) ; 
thread. start ( ) ; 

Thread. sleep (1000) ; 

thread. interrupt () ;  //  Interrupt  the  thread 

} 

} 

4.7.3  Compliant  Solution  (Close  Socket  Connection) 

This  compliant  solution  resumes  the  thread  by  having  the  shutdown  ( )  method  close  the  socket. 
The  readLine  ( )  method  throws  a  SocketException  when  the  socket  is  closed,  which  lets 
the  thread  proceed.  Note  that  there  is  no  way  to  keep  the  connection  alive  if  the  thread  is  to  be 
halted  cleanly  and  immediately. 

public  final  class  SocketReader  implements  Runnable  { 

//  ... 

public  void  readData ()  throws  IOException  { 

String  string; 
try  { 

while  ((string  =  in . readLine () )  !=  null)  { 

//  Blocks  until  end  of  stream  (null) 

1 

}  finally  { 


CMU/SEI-2010-TR-015  |  115 


THI06-J 


shutdown ( ) ; 

} 

} 

public  void  shutdown ()  throws  IOException  { 
socket . close  ( ) ; 

} 

public  static  void  main (String [ ]  args)  throws  IOException,  InterruptedException  { 
SocketReader  reader  =  new  SocketReader  ("somehost",  25); 

Thread  thread  =  new  Thread (reader ) ; 
thread. start ( ) ; 

Thread. sleep (1000) ; 
reader . shutdown ( ) ; 

} 

} 

After  the  shutdown  ( )  method  is  called  from  main  ( ) ,  the  finally  block  in  readData  ( ) 
executes  and  calls  shutdown  ( )  again,  closing  the  socket  for  a  second  time.  However,  this 
second  call  has  no  effect  if  the  socket  has  already  been  closed. 

When  performing  asynchronous  I/O,  a  j  ava .  nio .  channels  .  Selector  may  also  be  brought 
out  of  the  blocked  state  by  invoking  either  its  close  ( )  or  wakeup  ( )  method. 

A  boolean  flag  can  be  used  if  additional  operations  need  to  be  performed  after  emerging  from 
the  blocked  state.  When  supplementing  the  code  with  such  a  flag,  the  shutdown  ( )  method 
should  also  set  the  flag  to  false  so  that  the  thread  can  exit  cleanly  from  the  while  loop. 

4.7.4  Compliant  Solution  (Interruptible  Channel) 

This  compliant  solution  uses  an  interruptible  channel, 

java .  nio .  channels  .  SocketChannel,  instead  of  a  Socket  connection.  If  the  thread  per¬ 
forming  the  network  I/O  is  interrupted  using  the  Thread .  interrupt  ( )  method  while  it  is 
reading  the  data,  the  thread  receives  a  ClosedBylnterruptException,  and  the  channel  is 
closed  immediately.  The  thread’s  interrupted  status  is  also  set. 


public  final  class  SocketReader  implements  Runnable 

private  final  SocketChannel  sc; 

private  final  Object  lock  =  new  Object (); 

{ 

public  SocketReader (String  host,  int  port)  throws  IOException  { 

sc  =  SocketChannel . open (new  InetSocketAddress (host,  port)); 

} 

@Override  public  void  run()  { 

ByteBuffer  buf  =  ByteBuffer .allocate (1024) ; 

try  { 

synchronized  (lock)  { 

while  (! Thread. interrupted () )  { 

sc . read (buf) ; 
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II  ... 

} 

} 

}  catch  (IOException  ie)  { 

//  Forward  to  handler 

1 

} 

public  static  void  main (String [ ]  args)  throws  IOException,  InterruptedException  { 
SocketReader  reader  =  new  SocketReader ("somehost",  25); 

Thread  thread  =  new  Thread (reader ) ; 
thread. start ( ) ; 

Thread. sleep (1000) ; 
thread. interrupt ( ) ; 

} 

} 

This  technique  interrupts  the  current  thread.  However,  it  only  stops  the  thread  because  the  code 
polls  the  thread’s  interrupted  status  with  the  Thread .  interrupted  ( )  method  and  terminates 
the  thread  when  it  is  interrupted.  Using  a  SocketChannel  ensures  that  the  condition  in  the 
while  loop  is  tested  as  soon  as  an  interruption  is  received,  despite  the  read  being  a  blocking  opera¬ 
tion.  Similarly,  invoking  the  interrupt  ( )  method  of  a  thread  that  is  blocked  because  of 
java .  nio .  channels  .  Selector  also  causes  that  thread  to  awaken. 

4.7.5  Noncompliant  Code  Example  (Database  Connection) 

This  noncompliant  code  example  shows  a  thread-safe  DBConnector  class  that  creates  one  Java 
Database  Connectivity  (JDBC)  comiection  per  thread.  Each  connection  belongs  to  one  thread  and 
is  not  shared  by  other  threads.  This  is  a  common  use  case  because  JDBC  connections  are  not 
meant  to  be  shared  by  multiple  threads. 

public  final  class  DBConnector  implements  Runnable  { 
private  final  String  query; 

DBConnector (String  query)  { 
this. query  =  query; 

1 

@Override  public  void  run()  { 

Connection  connection; 
try  { 

//  Username  and  password  are  hard-coded  for  brevity 
connection  =  DriverManager . getConnection ( 

" j  dbc : driver : name" , 

"username" , 

"password" 

)  ; 

Statement  stmt  =  connection . createStatement () ; 

ResultSet  rs  =  stmt . executeQuery (query); 
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II  ... 

}  catch  (SQLException  e)  { 

/ /  Forward  to  handler 

} 

II  ... 

I 

public  static  void  main (String [ ]  args)  throws  InterruptedException  { 
DBConnector  connector  =  new  DBConnector ("suitable  query") ; 

Thread  thread  =  new  Thread (connector ) ; 
thread. start  ( ) ; 

Thread. sleep (5000) ; 
thread. interrupt ( ) ; 

} 

1 


Database  connections,  like  sockets,  are  not  inherently  interruptible.  Consequently,  this  design 
does  not  permit  a  client  to  cancel  a  task  by  closing  the  resource  if  the  corresponding  thread  is 
blocked  on  a  long-running  query  such  as  a  join. 

4.7.6  Compliant  Solution  (Statement .  cancel  ( ) ) 

This  compliant  solution  uses  a  ThreadLocal  wrapper  around  the  connection  so  that  a  thread 
calling  the  initialValue  ( )  method  obtains  a  unique  connection  instance.  The  advantage  of 
this  approach  is  that  a  cancelStatement  ( )  method  can  be  provided  so  that  other  threads  or 
clients  can  interrupt  a  long-running  query  when  required.  The  cancelStatement  ( )  method 
invokes  the  Statement .  cancel  ( )  method. 

public  final  class  DBConnector  implements  Runnable  { 
private  final  String  query; 
private  volatile  Statement  stmt; 

DBConnector (String  query)  { 
this. query  =  query; 
if  (getConnection ( )  !=  null)  { 

try  { 

stmt  =  getConnection (). createStatement () ; 

}  catch  (SQLException  e)  { 

/ /  Forward  to  handler 


private  static  final  ThreadLocal<Connection>  connectionHolder  = 
new  ThreadLocal<Connection> ( )  { 

Connection  connection  =  null; 

SOverride  public  Connection  initialValue ( )  { 

try  { 
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II  ... 

connection  =  DriverManager . getConnection ( 
" j  dbc : driver : name" , 

"username" , 

"password" 

) ; 

}  catch  (SQLException  e)  { 

//  Forward  to  handler 

} 

return  connection; 


public  Connection  getConnection  ( )  { 

return  connectionHolder . get ( ) ; 

| 

public  boolean  cancelStatement ( )  {  //  Allows  client  to  cancel  statement 

if  (stmt  !=  null)  { 
try  { 

stmt . cancel  ( ) ; 
return  true; 

}  catch  (SQLException  e)  { 

//  Forward  to  handler 

| 

I 

return  false; 

1 

SOverride  public  void  run()  { 
try  { 

if (stmt  ==  null  I  I  (stmt . getConnection ( )  !=  getConnection ()) )  { 

throw  new  IllegalStateException  ( ) ; 

I 

ResultSet  rs  =  stmt . executeQuery (query ) ; 

II  ... 

}  catch  (SQLException  e)  { 

//  Forward  to  handler 

} 

II  ... 
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public  static  void  main (String [ ]  args)  throws  InterruptedException  { 

DBConnector  connector  =  new  DBConnector ("suitable  query") ; 

Thread  thread  =  new  Thread (connector ) ; 
thread. start  ( ) ; 

Thread. sleep (5000) ; 
connector . cancelStatement ( ) ; 

} 

} 

The  Statement .  cancel  ( )  method  cancels  the  query,  provided  that  the  database  management 
system  (DBMS)  and  driver  both  support  cancellation.  It  is  not  possible  to  conform  with  this 
guideline  if  they  do  not. 

According  to  the  Java  API,  interface  Statement  documentation  [Sun  2009b] 

By  default,  only  one  ResultSet  object  per  Statement  object  can  be  open  at  the  same 
time.  Therefore,  if  the  reading  of  one  Resul  tSet  object  is  interleaved  with  the  reading  of 
another,  each  must  have  been  generated  by  different  Statement  objects. 

This  compliant  solution  ensures  that  only  one  ResultSet  is  associated  with  the  Statement 
belonging  to  an  instance,  and,  consequently,  only  one  thread  can  access  the  query  results. 

4.7.7  Risk  Assessment 

Failing  to  provide  facilities  for  thread  termination  can  cause  non-responsiveness  and  denial  of 
service. 
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5  Thread  Pools  (TPS)  Guidelines 


5.1  TPSOO-J.  Use  thread  pools  to  enable  graceful  degradation  of  service  during 
traffic  bursts 

Many  programs  must  address  the  problem  of  handling  a  series  of  incoming  requests.  The  Thread- 
Per-Message  design  pattern  is  the  simplest  concurrency  strategy  wherein  a  new  thread  is  created 
for  each  request  [Lea  2000a].  This  pattern  is  generally  preferred  to  sequential  executions  of  time- 
consuming,  I/O-bound,  session-based,  or  isolated  tasks. 

However,  this  pattern  also  has  several  pitfalls,  including  overheads  of  thread-creation  and  sche¬ 
duling,  task  processing,  resource  allocation  and  deallocation,  and  frequent  context  switching  [Lea 
2000a].  Furthermore,  an  attacker  can  cause  a  denial  of  service  by  overwhelming  the  system  with 
too  many  requests  all  at  once.  Instead  of  degrading  gracefully,  the  system  becomes  unresponsive, 
causing  a  denial  of  service.  From  a  safety  perspective,  one  component  can  exhaust  all  resources 
because  of  some  intermittent  error,  starving  all  other  components. 

Thread  pools  allow  a  system  to  service  as  many  requests  as  it  can  comfortably  sustain,  rather  than 
terminating  all  services  when  presented  with  a  deluge  of  requests.  Thread  pools  overcome  these 
issues  by  controlling  the  maximum  number  of  worker  threads  that  can  be  initialized  and  executed 
concurrently.  Every  object  that  supports  thread  pools  accepts  a  Runnable  or  Callable<T>  task 
and  stores  it  in  a  temporary  queue  until  resources  become  available.  Because  the  threads  in  a 
thread  pool  can  be  reused  and  efficiently  added  or  removed  from  the  pool,  thread  life-cycle  man¬ 
agement  overhead  is  minimized. 

5.1.1  Noncompliant  Code  Example 

This  noncompliant  code  example  demonstrates  the  Thread-Per-Message  design  pattern.  The 
RequestHandler  class  provides  a  public  static  factory  method  so  that  callers  can  obtain  its  in¬ 
stance.  The  handleRequest  ( )  method  is  subsequently  invoked  to  handle  each  request  in  its 
own  thread. 

class  Helper  { 

public  void  handle (Socket  socket)  { 

II ... 

} 

} 

final  class  RequestHandler  { 

private  final  Helper  helper  =  new  Helper)); 
private  final  ServerSocket  server; 

private  RequestHandler (int  port)  throws  IOException  { 
server  =  new  ServerSocket (port) ; 

1 
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public  static  RequestHandler  newlnstance ( )  throws  IOException  { 
return  new  RequestHandler (0) ;  //  Selects  next  available  port 

1 

public  void  handleRequest ( )  { 

new  Thread (new  Runnable ()  { 

public  void  run()  { 
try  { 

helper .handle (server . accept () ) ; 

}  catch  (IOException  e)  { 

//  Forward  to  handler 

} 

} 

} )  . start  ( ) ; 

1 


The  Thread-Per-Message  strategy  fails  to  provide  graceful  degradation  of  service.  As  more 
threads  are  created,  processing  continues  normally  until  some  scarce  resource  is  exhausted.  For 
example,  a  system  may  allow  only  a  limited  number  of  open  file  descriptors,  even  though  several 
more  threads  can  be  created  to  service  requests.  When  the  scarce  resource  is  memory,  the  system 
may  fail  abruptly,  resulting  in  a  denial  of  service. 

5.1.2  Compliant  Solution 

This  compliant  solution  uses  a  fixed-thread  pool  that  places  an  upper  bound  on  the  number  of 
concurrently  executing  threads.  Tasks  submitted  to  the  pool  are  stored  in  an  internal  queue.  That 
prevents  the  system  from  being  overwhelmed  when  trying  to  respond  to  all  the  incoming  requests 
and  allows  it  to  degrade  gracefully  by  serving  a  fixed  number  of  clients  at  a  particular  time  [Sun 
2008a], 

//  class  Helper  remains  unchanged 

final  class  RequestHandler  { 

private  final  Helper  helper  =  new  Helper  (); 
private  final  ServerSocket  server; 
private  final  ExecutorService  exec; 

private  RequestHandler (int  port,  int  poolSize)  throws  IOException  { 
server  =  new  ServerSocket  (port) ; 
exec  =  Executors . newFixedThreadPool (poolSize) ; 

} 

public  static  RequestHandler  newlnstance (int  poolSize)  throws  IOException  { 
return  new  RequestHandler (0,  poolSize); 

} 

public  void  handleRequest ( )  { 
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Future<?>  future  =  exec . submit (new  Runnable ()  { 

@Override  public  void  run()  { 
try  { 

helper .handle (server . accept () ) ; 

}  catch  (IOException  e)  { 

//  Forward  to  handler 

} 

} 

})  ; 

} 

//  ...  other  methods  such  as  shutting  down  the  thread  pool  and  task  cancellation  . . . 

} 

According  to  the  Java  API  documentation  for  the  Executor  interface  [Sun  2009b] 

[The  Interface  Executor  is]  An  object  that  executes  submitted  Runnable  tasks.  This  inter¬ 
face  provides  a  way  of  decoupling  task  submission  from  the  mechanics  of  how  each  task  will 
be  run,  including  details  of  thread  use,  scheduling,  etc.  An  Executor  is  normally  used  in¬ 
stead  of  explicitly  creating  threads. 

The  ExecutorService  interface  used  in  this  compliant  solution  derives  from  the 
j  ava  .  util .  concurrent .  Executor  interface.  The  ExecutorService  .  submit  ( )  me¬ 
thod  allows  callers  to  obtain  a  Future<V>  object.  This  object  encapsulates  the  as-yet-unknown 
result  of  an  asynchronous  computation  and  enables  callers  to  perform  additional  functions  such  as 
task  cancellation. 

The  choice  of  the  unbounded  newFixedThreadPool  is  not  always  optimal.  Refer  to  the  Java 
API  documentation  about  choosing  between  the  following  to  meet  specific  design  requirements 
[Sun  2009b]: 

•  newFixedThreadPool ( ) 

•  newCachedThreadPool ( ) 

•  newSingleThreadExecutor ( ) 

•  newScheduledThreadPool ( ) 
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5.1.3  Risk  Assessment 

Using  simplistic  concurrency  primitives  to  process  an  unbounded  number  of  requests  may  result 
in  severe  performance  degradation,  deadlock,  or  system  resource  exhaustion  and  denial  of  service. 
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5.2  TPS01-J.  Do  not  execute  interdependent  tasks  in  a  bounded  thread  pool 

A  bounded  thread  pool  allows  the  programmer  to  specify  the  upper  limit  on  the  number  of  threads 
that  can  execute  in  a  thread  pool  at  a  particular  time.  Tasks  that  depend  on  the  completion  of  other 
tasks  should  not  be  executed  in  a  bounded  thread  pool. 

A  form  of  deadlock  called  thread-starvation  deadlock  arises  when  all  the  threads  executing  in  the 
pool  are  blocked  on  tasks  that  have  not  yet  begun  executing  and  are  waiting  on  an  internal  queue. 
Thread-starvation  deadlock  occurs  when  currently  executing  tasks  submit  other  tasks  to  a  thread 
pool  and  wait  for  them  to  complete,  but  the  thread  pool  does  not  have  the  capacity  to  accommo¬ 
date  all  the  tasks  at  once. 

This  problem  is  deceptive  because  the  program  may  appear  to  function  correctly  when  fewer 
threads  are  needed.  In  some  cases,  the  issue  can  be  mitigated  by  choosing  a  larger  pool  size;  how¬ 
ever,  there  is  often  no  easy  way  to  determine  a  suitable  size. 

Similarly,  threads  in  a  thread  pool  may  not  be  recycled  if  two  executing  tasks  require  each  other 
to  complete  before  they  can  terminate.  A  blocking  operation  within  a  subtask  can  also  lead  to  un¬ 
bounded,  queue  growth  [Goetz  2006]. 

5.2.1  Noncompliant  Code  Example  (Interdependent  Subtasks) 

This  noncompliant  code  example  is  vulnerable  to  thread-starvation  deadlock.  It  consists  of  the 
ValidationService  class,  which  performs  various  input  validation  tasks  such  as  checking 
whether  a  user-supplied  field  exists  in  a  back-end  database. 

The  f  ieldAggregator  ()  method  accepts  a  variable  number  of  String  arguments  and  creates 
a  task  corresponding  to  each  argument  to  parallelize  processing.  The  task  performs  input  valida¬ 
tion  using  the  Validatelnput  class. 

In  turn,  the  Validatelnput  class  attempts  to  sanitize  the  input  by  creating  a  subtask  for  each 
request  using  the  Sanitize  Input  class.  All  tasks  are  executed  in  the  same  thread  pool.  The 
fieldAggregator  o  method  blocks  until  all  the  tasks  have  finished  executing  and,  when  all 
results  are  available,  returns  the  aggregated  results  as  a  StringBuilder  object  to  the  caller. 

public  final  class  ValidationService  { 
private  final  ExecutorService  pool; 

public  ValidationService  (int  poolSize)  { 

pool  =  Executors . newFixedThreadPool (poolSize) ; 

} 

public  void  shutdown ()  { 

pool . shutdown ( ) ; 

} 

public  StringBuilder  fieldAggregator (String .. .  inputs) 
throws  InterruptedException,  ExecutionException  { 
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StringBuilder  sb  =  new  StringBuilder () ; 

Future<String> [ ]  results  =  new  Future [ inputs . length] ;  //  Stores  the  results 

for  (int  i  =  0;  i  <  inputs . length;  i++)  {  //  Submits  the  tasks  to  thread  pool 

results [i]  =  pool . submit (new  ValidateInput<String> (inputs [i] ,  pool) ) ; 

1 

for  (int  i  =  0;  i  <  inputs . length;  i++)  {  //  Aggregates  the  results 
sb . append (results [i] . get ( ) ) ; 

} 

return  sb; 


public  final  class  ValidateInput<V>  implements  Callable<V>  { 
private  final  V  input; 
private  final  ExecutorService  pool; 

Validatelnput (V  input,  ExecutorService  pool)  { 
this. input  =  input; 
this. pool  =  pool; 

@Override  public  V  call()  throws  Exception  { 

//  If  validation  fails,  throw  an  exception  here 

Future<V>  future  =  pool . submit (new  SanitizeInput<V> (input) ) ;  //  Subtask 
return  (V) future . get () ; 

I 

} 

public  final  class  SanitizeInput<V>  implements  Callable<V>  { 
private  final  V  input; 

Sanitizelnput (V  input)  { 
this. input  =  input; 

} 

@Override  public  V  call()  throws  Exception  { 

//  Sanitize  input  and  return 
return  (V) input; 

I 

} 

Assuming  that  the  pool  size  is  set  to  six,  the  ValidationService  .  f  ieldAggregator  ( ) 
method  is  invoked  to  validate  the  six  arguments  and  submit  six  tasks  to  the  thread  pool.  Each  task 
submits  corresponding  subtasks  to  sanitize  the  input.  The  Sanitizelnput  subtasks  must  ex¬ 
ecute  before  these  threads  can  return  their  results.  However,  this  is  impossible  because  all  six 
threads  in  the  thread  pool  are  blocked.  Furthermore,  the  shutdown  ( )  method  cannot  shut  down 
the  thread  pool  when  it  contains  active  tasks. 
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Thread-starvation  deadlock  can  also  occur  when  a  single  threaded  Executor  is  used,  for  exam¬ 
ple,  when  the  caller  creates  several  subtasks  and  waits  for  the  results. 

5.2.2  Compliant  Solution  (No  Interdependent  Tasks) 

This  compliant  solution  modifies  the  ValidateInput<V>  class  so  that  the  Sanitizelnput 
tasks  are  executed  in  the  same  threads  as  the  Validate  Input  tasks  and  not  in  separate  threads. 
Consequently,  the  Validatelnput  and  Sanitizelnput  tasks  are  independent  and  need  not 
wait  for  each  other  to  complete.  The  Sanitizelnput  class  has  also  been  modified  to  not  im¬ 
plement  the  Callable  interface. 

public  final  class  ValidationService  { 

II  ... 

public  StringBuilder  fieldAggregator (String. . .  inputs) 
throws  InterruptedException,  ExecutionException  { 

//  ... 

for  (int  i  =  0;  i  <  inputs . length;  i++)  { 

//  Don't  pass-in  thread  pool 

results [i]  =  pool . submit (new  ValidateInput<String> (inputs [i] )) ; 

1 

//  ... 

} 

| 

//  Does  not  use  same  thread  pool 

public  final  class  ValidateInput<V>  implements  Callable<V>  { 
private  final  V  input; 

Validatelnput (V  input)  { 
this. input  =  input; 

| 

©Override  public  V  call()  throws  Exception  { 

//  If  validation  fails,  throw  an  exception  here 
return  (V)  new  Sanitizelnput (). sanitize (input) ; 


public  final  class  SanitizeInput<V>  {  //  No  longer  a  Callable  task 

public  Sanitizelnput ( )  {} 

public  V  sanitize (V  input)  { 

//  Sanitize  input  and  return 
return  input; 

1 
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Thread-starvation  issues  can  be  mitigated  by  choosing  a  large  thread  pool  size.  However,  an  un¬ 
trusted  caller  may  still  overwhelm  the  system  by  supplying  more  inputs  (see  guideline  “TPSOO-J. 
Use  thread  pools  to  enable  graceful  degradation  of  service  during  traffic  bursts”  on  page  121). 

Note  that  operations  with  further  constraints,  such  as  the  total  number  of  database  connections  or 
total  ResultSet  objects  open  at  a  particular  time,  impose  an  upper  bound  on  the  thread  pool  size 
because  each  thread  continues  to  block  until  the  resource  becomes  available. 

Private  static  ThreadLocal  variables  may  be  used  to  maintain  local  state  in  each  thread.  When 
using  thread  pools,  the  lifetime  of  ThreadLocal  variables  should  be  bounded  by  the  corres¬ 
ponding  task  [Goetz  2006].  Furthermore,  these  variables  should  not  be  used  to  communicate  be¬ 
tween  tasks.  There  are  additional  constraints  on  the  use  of  ThreadLocal  variables  in  thread 
pools  (see  guideline  “TPS04-J.  Ensure  ThreadLocal  variables  are  reinitialized  when  using  thread 
pools”  on  page  139). 

5.2.3  Noncompliant  Code  Example  (Subtasks) 

This  noncompliant  code  example  contains  a  series  of  subtasks  that  execute  in  a  shared  thread  pool 
[Gafter  2006].  The  BrowserManager  class  calls  perUser  ( ) ,  which  starts  tasks  that  invoke 
perProf  lie  ( )  .  The  perProf  ile  ( )  method  starts  tasks  that  invoke  perTab  ( ) ,  and,  in  turn, 
perTab  ( )  starts  tasks  that  invoke  doSomething  ( )  .  BrowserManager  then  waits  for  the 
tasks  to  finish.  The  threads  are  allowed  to  invoke  doSomething  ( )  in  any  order,  provided 
count  correctly  records  the  number  of  methods  executed. 

public  final  class  BrowserManager  { 

private  final  ExecutorService  pool  =  Executors . newFixedThreadPool ( 10 )  ; 
private  final  int  numberOf Times ; 

private  static  Atomiclnteger  count  =  new  Atomiclnteger ( ) ;  //  count  =  0 

public  BrowserManager (int  n)  { 
numberOf Times  =  n; 

1 

public  void  perUser ()  { 

methodlnvoker (numberOf Times ,  "perProf ile" ) ; 
pool . shutdown ( ) ; 

} 

public  void  perProfileO  { 

methodlnvoker (numberOf Times ,  "perTab") ; 

1 

public  void  perTab  ()  { 

methodlnvoker (numberOf Times ,  "doSomething") ; 

} 

public  void  doSomething ( )  { 

System. out .println (count . getAndlncrement ( ) ) ; 

} 


CMU/SEI-2010-TR-015  |  128 


TPS01-J 


public  void  methodlnvoker (int  n,  final  String  method)  { 
final  BrowserManager  manager  =  this; 

Callable<Object>  callable  =  new  Callable<Object>  ()  { 

©Override  public  Object  call()  throws  Exception  { 
Method  meth  =  manager . getClass (). getMethod (method) ; 
return  meth. invoke (manager) ; 


Collection<Callable<Object»  collection  =  Collections . nCopies  (n,  callable); 
try  { 

Collection<Future<Ob j ect»  futures  =  pool . invokeAll (collection) ; 

}  catch  (InterruptedException  e)  { 

//  Forward  to  handler 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 

h 

II  ... 

I 

public  static  void  main (String [ ]  args)  { 

BrowserManager  manager  =  new  BrowserManager (5) ; 
manager .perUser () ; 

| 

} 

Unfortunately,  this  program  is  susceptible  to  a  thread-starvation  deadlock.  For  example,  if  each  of 
the  five  perUser  tasks  spawns  five  perProf  ile  tasks,  which  each  spawn  a  perTab  task,  the 
thread  pool  will  be  exhausted,  and  perTab  ( )  will  not  be  able  to  allocate  any  additional  threads 
to  invoke  the  doSomething  ( )  method. 
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5.2.4  Compliant  Solution  (CallerRunsPolicy) 

This  compliant  solution  selects  and  schedules  tasks  for  execution,  avoiding  thread-starvation 
deadlock.  It  sets  the  CallerRunsPolicy  on  a  ThreadPoolExecutor  and  uses  a 
SynchronousQueue  [Gafter  2006].  The  policy  dictates  that  if  the  thread  pool  runs  out  of  avail¬ 
able  threads,  any  subsequent  tasks  will  run  in  the  thread  that  submitted  the  tasks. 

public  final  class  BrowserManager  { 

private  final  static  ThreadPoolExecutor  pool  = 

new  ThreadPoolExecutor (0,  10,  60L,  TimeUnit . SECONDS, 

new  SynchronousQueue<Runnable> () ) ; 
private  final  int  numberOf Times; 

private  static  Atomiclnteger  count  =  new  Atomiclnteger ( ) ;  //  count  =  0 
static  { 

pool . setRejectedExecutionHandler ( 

new  ThreadPoolExecutor . CallerRunsPolicy ( ) ) ; 

} 

//  ... 


According  to  Goetz  and  colleagues  [Goetz  2006] 

A  SynchronousQueue  is  not  really  a  queue  at  all,  hut  a  mechanism  for  managing  han- 
doffs  between  threads.  In  order  to  put  an  element  on  the  SynchronousQueue,  another 
thread  must  already  be  waiting  to  accept  the  handoff.  It  no  thread  is  waiting  but  the  current 
pool  size  is  less  than  the  maximum,  ThreadPoolExecutor  creates  a  new  thread;  other¬ 
wise  the  task  is  rejected  according  to  the  saturation  policy. 

According  to  the  Java  API  [Sun  2009b],  the  CallerRunsPolicy  class  is 

a  handler  for  rejected  tasks  that  runs  the  rejected  task  directly  in  the  calling  thread  of  the 
execute  method,  unless  the  executor  has  been  shut  down,  in  which  case  the  task  is  dis¬ 
carded 

In  this  compliant  solution,  tasks  that  have  other  tasks  waiting  to  accept  the  handoff  are  added  to 
the  SynchronousQueue  when  the  thread  pool  is  full.  For  example,  tasks  corresponding  to 
perTab  ( )  are  added  to  the  SynchronousQueue  because  the  tasks  corresponding  to 
perProf  ile  ( )  are  waiting  to  receive  the  handoff.  Once  the  pool  is  full,  additional  tasks  are  re¬ 
jected,  according  to  the  saturation  policy  in  effect.  Because  the  CallerRunsPolicy  is  used  to 
handle  these  rejected  tasks,  all  the  rejected  tasks  are  executed  in  the  main  thread  that  started  the 
initial  tasks.  When  all  the  threads  corresponding  to  perTab  ( )  have  finished  executing,  the  next 
set  of  tasks  corresponding  to  perProf  ile  ( )  are  added  to  the  SynchronousQueue  because 
the  handoff  is  subsequently  used  by  the  perUser  ( )  tasks. 

The  CallerRunsPolicy  allows  the  graceful  degradation  of  service  when  faced  with  many  re¬ 
quests  by  distributing  the  workload  from  the  thread  pool  to  the  work  queue.  Because  the  submit¬ 
ted  tasks  do  not  block  for  any  reason  other  than  waiting  for  other  tasks  to  complete,  the  policy 
guarantees  that  the  current  thread  can  handle  multiple  tasks  sequentially.  The  policy  would  not 
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prevent  thread-starvation  deadlock  if  the  tasks  were  to  block  for  some  other  reason,  such  as  net¬ 
work  I/O.  Furthermore,  because  SynchronousQueue  does  not  store  tasks  indefinitely  for  future 
execution,  there  is  no  unbounded  queue  growth,  and  all  tasks  are  handled  by  the  current  thread  or 
a  thread  in  the  thread  pool. 

This  compliant  solution  is  subject  to  the  vagaries  of  the  thread  scheduler,  which  may  not  schedule 
the  tasks  optimally.  However,  it  avoids  thread-starvation  deadlock. 

5.2.5  Risk  Assessment 

Executing  interdependent  tasks  in  a  thread  pool  can  lead  to  denial  of  service. 
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5.3  TPS02-J.  Ensure  that  tasks  submitted  to  a  thread  pool  are  interruptible 

Do  not  submit  tasks  that  do  not  support  interruption  using  Thread .  interrupt  ( )  to  a  thread 
pool  if  it  is  necessary  to  shut  down  the  thread  pool  or  cancel  individual  tasks  within  it. 

According  to  the  Java  API  interface  [Sun  2009b],  the 

j ava . util . concurrent . ExecutorService . shutdownNow ( )  method 

Attempts  to  stop  all  actively  executing  tasks,  halts  the  processing  of  waiting  tasks,  and  re¬ 
turns  a  list  of  the  tasks  that  were  awaiting  execution.  There  are  no  guarantees  beyond  best- 
effort  attempts  to  stop  processing  actively  executing  tasks.  For  example,  typical  implementa¬ 
tions  will  cancel  via  Thread .  interrupt  (),  so  any  task  that  fails  to  respond  to  interrupts 
may  never  terminate. 

Similarly,  when  attempting  to  cancel  individual  tasks  within  the  thread  pool  using  the 
Future .  cancel  ( )  method,  ensure  that  the  tasks  support  interruption. 

5.3.1  Noncompliant  Code  Example  (Shutting  Down  Thread  Pools) 

This  noncompliant  code  example  submits  the  SocketReader  class  as  a  task  to  the  thread  pool 
declared  in  PoolService. 

public  final  class  SocketReader  implements  Runnable  {  //  Thread-safe  class 
private  final  Socket  socket; 
private  final  Buf f eredReader  in; 
private  final  Object  lock  =  new  Object (); 

public  SocketReader (String  host,  int  port)  throws  IOException  { 
this. socket  =  new  Socket (host,  port); 

this. in  =  new  Buff eredReader (new  InputStreamReader (this . socket . getlnputStream ())) ; 

} 

//  Only  one  thread  can  use  the  socket  at  a  particular  time 
©Override  public  void  run()  { 
try  { 

synchronized  (lock)  { 
readData ( ) ; 

} 

}  catch  (IOException  ie)  { 

/ /  Forward  to  handler 


public  void  readData ()  throws  IOException  { 
String  string; 
try  { 

while  ((string  =  in . readLine ( ) )  !=  null)  { 

//  Blocks  until  end  of  stream  (null) 

I 

}  finally  { 


CMU/SEI-2010-TR-015  |  132 


TPS02-J 


shutdown ( ) ; 

} 

} 

public  void  shutdown ()  throws  IOException  { 
socket . close ( )  ; 

} 

}: 

public  final  class  PoolService  { 

private  final  ExecutorService  pool; 

public  PoolService (int  poolSize)  { 

pool  =  Executors . newFixedThreadPool (poolSize) ; 

} 

public  void  doSomething ( )  throws  InterruptedException,  IOException  { 
pool . submit (new  SocketReader ( "somehost" ,  8080)); 

//  ... 

List<Runnable>  awaitingTasks  =  pool . shutdownNow ( ) ; 

i 

public  static  void  main (String [ ]  args)  throws  InterruptedException,  IOException  { 
PoolService  service  =  new  PoolService (5) ; 
service . doSomething ( ) ; 

} 

Because  the  task  does  not  support  interruption  using  the  Thread .  interrupt  ( )  method,  there 
is  no  guarantee  that  the  shutdownNow  ( )  method  will  shut  down  the  thread  pool.  Using  the  latter 
does  not  fix  the  problem  either  because  it  waits  until  all  the  executing  tasks  have  finished. 

Similarly,  tasks  that  use  some  mechanism  other  than  Thread .  interrupted  ( )  to  determine 
when  to  shut  down  will  be  unresponsive  to  shutdown  ( )  or  shutdownNow  ( ) .  For  instance, 
tasks  that  check  a  volatile  flag  to  determine  whether  it  is  safe  to  shut  down  will  be  unresponsive  to 
these  methods.  The  guideline  “THI05-J.  Do  not  use  Thread .  stop  ( )  to  terminate  threads”  on 
page  1 1 0  provides  more  information  on  using  a  flag  to  terminate  threads. 

5.3.2  Compliant  Solution  (Submit  Interruptible  Tasks) 

This  compliant  solution  defines  an  interruptible  version  of  the  SocketReader  class,  which  is 
instantiated  and  submitted  to  the  thread  pool. 

public  final  class  SocketReader  implements  Runnable  { 
private  final  SocketChannel  sc; 
private  final  Object  lock  =  new  Object (); 

public  SocketReader (String  host,  int  port)  throws  IOException  { 
sc  =  SocketChannel . open (new  InetSocketAddress (host ,  port)); 


CMU/SEI-2010-TR-015  |  133 


TPS02-J 


©Override  public  void  run()  { 

ByteBuffer  buf  =  ByteBuffer . allocate ( 1024 ) , 
try  { 

synchronized  (lock)  { 

while  (! Thread. interrupted () )  { 
sc .  read  (buf)  ; 

//  ... 


}  catch  (IOException  ie)  { 
//  Forward  to  handler 


public  final  class  PoolService  { 

II  ... 


5.3.3  Exceptions 

TPS02-EX1:  Short -running  tasks  that  execute  without  blocking  are  not  required  to  adhere  to  this 
guideline. 

5.3.4  Risk  Assessment 

Submitting  tasks  that  are  not  interruptible  may  preclude  the  thread  pool  from  shutting  down  and 
cause  denial  of  service. 
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P4 

L3 
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5.4  TPS03-J.  Ensure  that  tasks  executing  in  a  thread  pool  do  not  fail  silently 

Long-running  tasks  should  provide  a  mechanism  for  notifying  the  application  upon  abnormal  ter¬ 
mination.  Failure  to  do  so  does  not  cause  any  resource  leaks  because  the  threads  in  the  pool  are 
still  recycled,  but  it  makes  failure  diagnosis  extremely  difficult. 

The  best  way  to  handle  exceptions  at  the  application  level  is  to  use  an  exception  handler.  The 
handler  can  perform  diagnostic  actions,  clean  up  and  shut  down  the  JVM,  or  simply  log  the  details 
of  the  failure. 

5.4.1  Noncompliant  Code  Example  (Abnormal  Task  Termination) 

This  noncompliant  code  example  consists  of  the  PoolService  class  that  encapsulates  a  thread 
pool  and  a  runnable  Task  class.  The  Task .  run  ( )  method  can  throw  runtime  exceptions  such  as 

NullPointerException. 

final  class  PoolService  { 

private  final  ExecutorService  pool  =  Executors . newFixedThreadPool ( 10 ) ; 

public  void  doSomething ( )  { 

pool . execute (new  Task()); 

I 

} 

final  class  Task  implements  Runnable  { 

@Override  public  void  run()  { 

II  ... 

throw  new  NullPointerException () ; 

//  ... 

1 

} 

The  task  does  not  notify  the  application  when  it  terminates  unexpectedly  as  a  result  of  the  runtime 
exception.  Moreover,  it  does  not  use  any  recovery  mechanism.  Consequently,  if  Task  throws  a 
NullPointerException,  the  exception  is  ignored. 

5.4.2  Compliant  Solution  (ThreadPoolExecutor  Hooks) 

Task-specific  recovery  or  clean-up  actions  can  be  perfonned  by  overriding  the 
af  terExecute  ( )  hook  of  the  j  ava  .  util .  concurrent .  ThreadPoolExecutor  class. 
This  hook  is  called  when  a  task  concludes  successfully  by  executing  all  the  statements  in  its 
run  ( )  method  or  halts  because  of  an  exception.  ( j  ava .  lang .  Error  might  not  be  captured  on 
specific  implementations.  See  Bug  ID  6450211  for  more  information  [Sun  2008b].)  When  using 
this  approach,  substitute  the  executor  service  with  a  custom  ThreadPoolExecutor  that  over¬ 
rides  the  af  terExecute  ( )  hook  as  shown  below: 

final  class  PoolService  { 

//  The  values  have  been  hard-coded  for  brevity 

ExecutorService  pool  =  new  CustomThreadPoolExecutor ( 10 ,  10,  10,  TimeUnit . SECONDS, 
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II  ... 

1 


new  ArrayBlockingQueue<Runnable> (10) ); 


class  CustomThreadPoolExecutor  extends  ThreadPoolExecutor  { 
//  ...  Constructor  . . . 


@Override 

public  void  afterExecute (Runnable  r,  Throwable  t)  { 
super . afterExecute (r,  t) ; 
if  (t  ! =  null)  { 

//  Exception  occurred,  forward  to  handler 

i 

//  ...  Perform  task-specific  clean-up  actions 


SOverride 

public  void  terminated ()  { 
super . terminated ( )  ; 

//  ...  Perform  final  clean-up  actions 

i 

} 


The  terminated  ( )  hook  is  called  after  all  the  tasks  have  finished  executing  and  the  Executor 
has  terminated  cleanly.  This  hook  can  be  overridden  to  release  resources  acquired  by  the  thread 
pool,  much  like  a  finally  block. 


5.4.3  Compliant  Solution  (Uncaught  Exception  Handler) 

This  compliant  solution  sets  an  uncaught  exception  handler  on  behalf  of  the  thread  pool.  A 
ThreadFactory  argument  is  passed  to  the  thread  pool  during  construction.  The  factory  is  re¬ 
sponsible  for  creating  new  threads  and  setting  the  uncaught  exception  handler  on  their  behalf.  The 
Task  class  is  unchanged  from  the  noncompliant  code  example. 

final  class  PoolService  { 

private  static  final  ThreadFactory  factory  =  new 

ExceptionThreadFactory (new  MyExceptionHandler ( ) ) ; 
private  static  final  ExecutorService  pool  = 

Executors . newFixedThreadPool (10,  factory) ; 

public  void  doSomething ( )  { 

pool . execute (new  Task());  //  Task  is  a  runnable  class 

} 

public  static  class  ExceptionThreadFactory  implements  ThreadFactory  { 
private  static  final  ThreadFactory  defaultFactory  = 

Executors . def aultThreadFactory ( ) ; 
private  final  Thread. UncaughtExceptionHandler  handler; 
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public  ExceptionThreadFactory (Thread. UncaughtExceptionHandler  handler)  { 
this. handler  =  handler; 

} 

@Override  public  Thread  newThread (Runnable  run)  { 

Thread  thread  =  defaultFactory . newThread (run) ; 
thread. setUncaughtExceptionHandler (handler) ; 
return  thread; 


public  static  class  MyExceptionHandler  extends  ExceptionReporter 
implements  Thread. UncaughtExceptionHandler  { 

//  ... 

@Override  public  void  uncaughtException (Thread  thread,  Throwable  t)  { 

//  Recovery  or  logging  code 

} 

} 

} 

The  ExecutorService .  submit  ( )  method  can  be  used  to  submit  a  task  to  a  thread  pool  in¬ 
stead  of  the  execute  ( )  method  to  obtain  a  Future  object.  Note  that  the  uncaught  exception 
handler  is  not  called  if  ExecutorService .  submit  ( )  is  invoked.  This  is  because  the  thrown 
exception  is  considered  to  be  part  of  the  return  status  and  is  consequently  wrapped  in  an 
ExecutionException  and  re-thrown  by  the  Future .  get  ( )  method  [Goetz  2006]. 
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5.4.4  Compliant  Solution  (Future<v>  and  submit  ( ) ) 

This  compliant  solution  invokes  the  ExecutorService .  submit  ( )  method  to  submit  the  task 
so  that  a  Future  object  can  be  obtained.  It  uses  the  Future  object  to  let  the  task  re-throw  the 
exception  so  that  it  can  be  handled  locally. 

final  class  PoolService  { 

private  final  ExecutorService  pool  =  Executors . newFixedThreadPool ( 10 ) ; 

public  void  doSomething ( )  { 

Future<?>  future  =  pool . submit (new  Task()); 

//  ... 

try  { 

future . get  ( )  ; 

}  catch  (InterruptedException  e)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 
}  catch  (ExecutionException  e)  { 

Throwable  exception  =  e . getCause ( ) ; 

//  Forward  to  exception  reporter 

} 

1 

} 

Furthermore,  any  exception  that  prevents  doSomething  ( )  from  obtaining  the  Future  value 
can  be  handled  as  required. 

5.4.5  Exceptions 

TPS03-EX1:  This  guideline  may  be  violated  if  the  code  for  all  runnable  and  callable  tasks  has 
been  audited  to  ensure  that  no  exceptional  conditions  are  possible.  Nonetheless,  it  is  usually  a 
good  practice  to  install  a  task-specific  or  global  exception  handler  to  initiate  recovery  or  log  the 
exceptional  condition. 

5.4.6  Risk  Assessment 

Failing  to  provide  a  mechanism  for  reporting  that  tasks  in  a  thread  pool  failed  as  a  result  of  an 
exceptional  condition  can  make  it  harder  to  find  the  source  of  the  issue. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

TPS03-  J 

low 

probable 

medium 

P4 

L3 

5.4.7  References 

[Goetz  2006]  Chapter  7.3,  “  Handling  abnormal  thread  termination” 

[Sun  2009b]  Interfaces  ExecutorService,  ThreadFactory  and  class  Thread 
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5.5  TPS04-J.  Ensure  ThreadLocal  variables  are  reinitialized  when  using  thread 
pools 

The  j  ava .  lang .  ThreadLocal<T>  class  provides  thread-local  variables.  According  to  the 
Java  API  [Sun  2009b] 

These  variables  differ  from  their  normal  counterparts  in  that  each  thread  that  accesses  one 
(via  its  get  or  set  method)  has  its  own,  independently  initialized  copy  of  the  variable. 
ThreadLocal  instances  are  typically  private  static  fields  in  classes  thatwish  to  asso¬ 
ciate  state  with  a  thread  (e.g.,  a  user  ID  or  Transaction  ID). 

The  use  of  ThreadLocal  objects  requires  care  in  classes  whose  objects  are  required  to  be  ex¬ 
ecuted  by  multiple  threads  in  a  thread  pool.  The  technique  of  thread  pooling  allows  threads  to  be 
reused  when  thread  creation  overhead  is  too  expensive  or  when  creating  an  unbounded  number  of 
threads  can  diminish  the  reliability  of  the  system.  Every  thread  that  enters  the  pool  expects  to  see 
an  object  in  its  initial,  default  state.  However,  when  ThreadLocal  objects  are  modified  from  a 
thread  that  is  subsequently  made  available  for  reuse,  the  reused  thread  sees  the  state  of  the 
ThreadLocal  object  as  set  by  the  previous  thread  [Arnold  2006]. 

5.5.1  Noncompliant  Code  Example 

This  noncompliant  code  example  consists  of  an  enumeration  of  days  (Day)  and  two  classes 
(Diary  and  DiaryPool).  The  Diary  class  uses  a  ThreadLocal  variable  to  store  thread- 
specific  information,  such  as  each  thread’s  current  day.  The  initial  value  of  the  current  day  is 
Monday;  this  can  be  changed  later  by  invoking  the  setDay  ( )  method.  The  class  also  contains  a 
threadSpecif  icTask  ( )  instance  method  that  performs  a  thread-specific  task. 

The  DiaryPool  class  consists  of  the  doSomethingl  ( )  and  doSomething2  ( )  methods  that 
each  start  a  thread.  The  doSomethingl  ( )  method  changes  the  initial  (default)  value  of  the  day 
to  Friday  and  invokes  threadSpecif  icTask  ( ) .  On  the  other  hand,  doSomething2  ( )  relies 
on  the  initial  value  of  the  day  (Monday)  diary  and  invokes  threadSpecif  icTask  ( ) .  The 
main  ( )  method  creates  one  thread  using  doSomethingl  ( )  and  two  more  using 
doSomething2  () . 

public  enum  Day  { 

MONDAY,  TUESDAY,  WEDNESDAY,  THURSDAY,  FRIDAY,  SATURDAY,  SUNDAY; 

} 

public  final  class  Diary  { 

private  static  final  ThreadLocal<Day>  days  = 
new  ThreadLocal<Day> ( )  { 

//  Initialize  to  Monday 
protected  Day  initialValue ( )  { 
return  Day. MONDAY; 

) 

}  ; 

private  static  Day  currentDayO  { 
return  days.getO; 
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public  static  void  setDay(Day  newDay)  { 
days . set (newDay) ; 

} 

//  Performs  some  thread-specific  task 
public  void  threadSpecif icTask ( )  { 

//  Do  task  . . . 

f 

} 

public  final  class  DiaryPool  { 

final  int  NoOfThreads  =  2;  //  Maximum  number  of  threads  allowed  in  pool 
final  Executor  exec; 
final  Diary  diary; 

DiaryPool  ()  { 

exec  =  (Executor)  Executors . newFixedThreadPool (NoOfThreads) ; 
diary  =  new  Diary (); 

} 

public  void  doSomethingl ( )  { 

exec . execute (new  Runnable ()  { 

@Override  public  void  run()  { 

Diary . setDay (Day . FRIDAY) ; 
diary . threadSpecif icTask ( ) ; 

} 

}>; 

| 

public  void  doSomething2 ( )  { 

exec . execute (new  Runnable ()  { 

@Override  public  void  run()  { 
diary . threadSpecif icTask ( ) ; 

i 

jhj 

i 

public  static  void  main (String [ ]  args)  { 

DiaryPool  dp  =  new  DiaryPool  (); 


dp . doSomethingl () ; 

// 

Thread 

1, 

requires 

current 

day 

as 

Friday 

dp . doSomething2 () ; 

// 

Thread 

2, 

requires 

current 

day 

as 

Monday 

dp . doSomething2 () ; 

// 

Thread 

3, 

requires 

current 

day 

as 

Monday 
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The  DiaryPool  class  creates  a  thread  pool  that  reuses  a  fixed  number  of  threads  operating  off  a 
shared,  unbounded  queue.  At  any  point,  at  most,  NoOf  Threads  threads  are  actively  processing 
tasks.  If  additional  tasks  are  submitted  when  all  threads  are  active,  they  will  wait  in  the  queue  un¬ 
til  a  thread  is  available.  The  thread-local  state  of  the  thread  persists  when  a  thread  is  recycled. 


The  following  table  shows  a  possible  execution  order: 


Time 

Task 

Pool  Thread 

Submitted  By  Method 

Day 

1 

U 

1 

doSomethingl  () 

Friday 

2 

2 

doSomething2() 

Monday 

3 

h 

1 

doSomething2() 

Friday 

In  this  execution  order,  the  two  tasks  ( t2  and  1 3)  that  started  using  doSomething2  ( )  are  ex¬ 
pected  to  observe  the  current  day  as  Monday.  However,  because  pool  thread  1  is  reused,  ob¬ 
serves  the  day  to  be  Friday. 

5.5.2  Noncompliant  Code  Example  (Increase  Thread  Pool  Size) 

This  noncompliant  code  example  increases  the  size  of  the  thread  pool  from  two  to  three  in  an  at¬ 
tempt  to  mitigate  the  issue. 

public  final  class  DiaryPool  { 
final  int  NoOf Threads  =  3; 

//  ... 

} 


Although  increasing  the  size  of  the  thread  pool  resolves  the  problem  for  this  example,  it  is  not  a 
scalable  solution  because  changing  the  thread  pool  size  is  insufficient  when  more  tasks  can  be 
submitted  to  the  pool. 

5.5.3  Compliant  Solution  (try-finally  Clause) 

This  compliant  solution  adds  the  removeDay  ( )  method  to  the  Diary  class  and  wraps  the  state¬ 
ments  in  the  doSomethingl  ( )  method  of  the  DiaryPool  class  in  a  try-finally  block.  The 
finally  block  restores  the  initial  state  of  the  thread-local  days  object  by  removing  the  current 
thread’s  value  from  it. 

public  final  class  Diary  { 

//  ... 

public  static  void  removeDay ()  { 

days . remove  ( ) ; 

i 

} 

public  final  class  DiaryPool  { 

II  ... 

public  void  doSomethingl ( )  { 
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exec . execute (new  Runnable ()  { 

@Override  public  void  run()  { 
try  { 

Diary . setDay (Day . FRIDAY) ; 
diary . threadSpecif icTask ( ) ; 

}  finally  { 

Diary . removeDay () ;  //  Diary . setDay (Day. MONDAY)  can  also  be  used 


}}? 

} 

//  ... 

} 

If  the  thread-local  variable  is  read  by  the  same  thread  again,  it  is  reinitialized  using  the 
initialValue  ( )  method,  unless  the  thread  has  already  set  the  variable’s  value  explicitly  [Sun 
2009b].  This  solution  transfers  the  responsibility  for  maintenance  to  the  client  (DiaryPool)  but 
is  a  good  option  when  the  Diary  class  cannot  be  modified. 

5.5.4  Compliant  Solution  (bef  oreExecute  ( ) ) 

This  compliant  solution  uses  a  custom  ThreadPoolExecutor  that  extends 
ThreadPoolExecutor  and  overrides  the  bef  oreExecute  ( )  method.  That  method  is  in¬ 
voked  before  the  Runnable  task  is  executed  in  the  specified  thread.  The  method  reinitializes  the 
thread-local  variable  before  task  r  is  executed  by  thread  t. 

class  CustomThreadPoolExecutor  extends  ThreadPoolExecutor  { 

public  CustomThreadPoolExecutor (int  corePoolSize,  int  maximumPoolSize, 

long  keepAliveTime,  TimeUnit  unit,  BlockingQueue<Runnable>  workQueue)  { 
super (corePoolSize,  maximumPoolSize,  keepAliveTime,  unit,  workQueue); 
t 

@Override 

public  void  beforeExecute (Thread  t.  Runnable  r)  { 
if  (t  ==  null  I  I  r  ==  null)  { 

throw  new  NullPointerException ( ) ; 

} 

Diary . setDay (Day .MONDAY) ; 
super .beforeExecute (t,  r) ; 

} 

} 
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public  final  class  DiaryPool  { 

II  ... 

DiaryPool  ()  { 

exec  =  new  CustomThreadPoolExecutor (NoOf Threads,  NoOf Threads, 

10,  TimeUnit . SECONDS ,  new  ArrayBlockingQueue<Runnable> ( 10 ) ) ; 
diary  =  new  Diary  (); 

} 

II  ... 

} 

5.5.5  Exceptions 

TPS04-EX1:  There  is  no  need  to  reinitialize  a  ThreadLocal  object  that  does  not  change  state 
after  initialization.  For  example,  there  may  be  only  one  type  of  database  connection  represented 
by  the  initial  value  of  the  ThreadLocal  object. 

5.5.6  Risk  Assessment 

Objects  using  ThreadLocal  data  and  executed  by  different  threads  in  a  thread  pool  without  rei¬ 
nitialization  might  be  in  an  unexpected  state  when  reused. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

TPS04-  J 

medium 

probable 

high 

P4 

L3 

5.5.7  References 

[Arnold  2006]  Section  14.13,  “ThreadLocal  Variables” 

[Sun  2009b]  class  j ava .  lang .  ThreadLocal<T> 
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6  Thread-Safety  Miscellaneous  (TSM)  Guidelines 


6.1  TSMOO-J.  Do  not  override  thread-safe  methods  with  methods  that  are  not 
thread-safe 

Overriding  thread-safe  methods  with  methods  that  are  not  thread-safe  can  result  in  improper  syn¬ 
chronization,  if  the  client  inadvertently  operates  on  an  instance  of  the  subclass.  An  overridden 
synchronized  method’s  contract  can  be  violated,  if  a  subclass  provides  an  implementation  that  is 
not  safe  for  concurrent  use. 

Overriding  thread-safe  methods  with  methods  that  are  not  thread-safe  is  not,  in  itself,  an  error. 
However,  it  is  disallowed  by  this  guideline  because  it  may  easily  result  in  errors  that  are  difficult 
to  diagnose. 

The  locking  strategy  of  classes  designed  for  inheritance  should  always  be  documented.  This  in¬ 
formation  can  subsequently  be  used  to  determine  an  appropriate  locking  strategy  for  subclasses 
(see  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that  may  interact 
with  untrusted  code”  on  page  41). 

6.1.1  Noncompliant  Code  Example  (Synchronized  Method) 

This  noncompliant  code  example  overrides  the  synchronized  doSomething  ( )  method  in  the 
Base  class  with  an  unsynchronized  method  in  the  Derived  subclass. 

class  Base  { 

public  synchronized  void  doSomething ( )  { 

//  ... 

1 

} 

class  Derived  extends  Base  { 

@Override  public  void  doSomething ( )  { 

II  ... 

} 

) 

The  doSomething  ( )  method  of  the  Base  class  can  be  used  safely  by  multiple  threads,  but  in¬ 
stances  of  the  Derived  subclass  cannot. 

This  programming  error  can  be  difficult  to  diagnose  because  threads  that  accept  instances  of 
Base  can  also  accept  instances  of  its  subclasses.  Consequently,  clients  could  be  unaware  that  they 
are  operating  on  an  instance  of  the  subclass  of  a  thread-safe  class  that  is  not  thread-safe. 
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6.1.2  Compliant  Solution  (Synchronized  Method) 

This  compliant  solution  synchronizes  the  doSomething  ( )  method  of  the  subclass. 

class  Base  { 

public  synchronized  void  doSomething ( )  { 

II  ... 
i 
I 

class  Derived  extends  Base  { 

@Override  public  synchronized  void  doSomething ( )  { 

//  ... 

} 

1 

This  compliant  solution  does  not  violate  guideline  “LCKOO-J.  Use  private  final  lock  objects  to 
synchronize  classes  that  may  interact  with  untrusted  code”  on  page  41  because  the  accessibility  of 
the  class  is  package-private.  That  type  of  accessibility  is  allowable  when  untrusted  code  cannot 
infiltrate  the  package. 

6.1.3  Compliant  Solution  (Private  Final  Lock  Object) 

This  compliant  solution  ensures  that  the  Derived  class  is  thread-safe  by  overriding  the  synchro¬ 
nized  doSomething  ( )  method  of  the  Base  class  with  a  method  that  synchronizes  on  a  private 
final  lock  object. 

class  Base  { 

public  synchronized  void  doSomething))  { 

II  ... 

} 

\ 

class  Derived  extends  Base  { 

private  final  Object  lock  =  new  Object)); 

@Override  public  void  doSomething))  { 
synchronized  (lock)  { 

II  ... 

1 

| 

} 

This  is  an  acceptable  solution,  provided  the  Derived  class  has  a  consistent  locking  policy. 
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6.1.4  Noncompiiant  Code  Example  (Private  Lock) 

This  noncompiiant  code  example  defines  a  doSomething  ( )  method  in  the  Base  class  that  uses 
a  private  final  lock,  in  accordance  with  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  syn¬ 
chronize  classes  that  may  interact  with  untrusted  code”  on  page  4 1 . 

class  Base  { 

private  final  Object  lock  =  new  Object  (); 

public  void  doSomething ( )  { 

synchronized  (lock)  { 

II  ... 

I 


class  Derived  extends  Base  { 

@Override  public  void  doSomething ( )  { 

try  { 

super . doSomething ( ) ; 

}  finally  { 

logger . log (Level . FINE,  "Did  something"); 

I 


It  is  possible  for  multiple  threads  to  cause  the  entries  to  be  logged  in  an  order  that  differs  from  the 
order  in  which  the  tasks  are  performed.  Consequently,  the  doSomething  ( )  method  of  the 
Derived  class  cannot  be  used  safely  by  multiple  threads  because  it  is  not  thread-safe. 

6.1.5  Compliant  Solution  (Private  Lock) 

This  compliant  solution  synchronizes  the  doSomething  ( )  method  of  the  subclass  using  a  pri¬ 
vate  final  lock  object. 

class  Base  { 

private  final  Object  lock  =  new  Object (); 

public  void  doSomething ( )  { 

synchronized  (lock)  { 

II  ... 

} 


class  Derived  extends  Base  { 

private  final  Object  lock  =  new  Object  (); 

((Override  public  void  doSomething  ( )  { 
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synchronized  (lock)  { 
try  { 

super . doSomething ( ) ; 

}  finally  { 

logger . log (Level . FINE,  "Did  something") ; 

} 

| 

} 

} 

Note  that  the  Base  and  Derived  objects  maintain  distinct  locks  that  are  inaccessible  from  each 
others’  classes.  Consequently,  Derived  can  provide  thread-safety  guarantees  independent  of 

Base. 


6.1.6  Risk  Assessment 

Overriding  thread-safe  methods  with  methods  that  are  not  thread-safe  can  result  in  unexpected 
behavior. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

TSM00-  J 

low 

probable 

medium 

P4 

L3 

6.1.7  References 

[Sun  2009b] 

[Sun  2008b]  Sun  bug  database,  Bug  ID  4294756 
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6.2  TSM01-J.  Do  not  let  the  “this”  reference  escape  during  object  construction 

According  to  the  Java  Language  Specification  [Gosling  2005],  Section  15.8.3,  “this” 

When  used  as  a  primary  expression,  the  keyword  this  denotes  a  value  that  is  a  reference  to 
the  object  for  which  the  instance  method  was  invoked  (§15.12),  or  to  the  object  being  con¬ 
structed.  The  type  of  this  is  the  class  C  within  which  the  keyword  this  occurs.  At  run  time, 
the  class  of  the  actual  object  referred  to  may  be  the  class  C  or  any  subclass  of  C. 

The  this  reference  is  said  to  have  escaped  when  it  is  made  available  beyond  its  current  scope. 
Common  ways  by  which  the  this  reference  can  escape  include 

•  returning  this  from  a  non-private,  overridable  method  that  is  invoked  from  the  constructor 
of  a  class  whose  object  is  being  constructed.  (For  more  information,  see  guideline  “MET04-J. 
Ensure  that  constructors  do  not  call  overridable  methods.”10) 

•  returning  this  from  a  non-private  method  of  a  mutable  class,  which  allows  the  caller  to  ma¬ 
nipulate  the  object’s  state  indirectly.  This  commonly  occurs  in  method-chaining  implementa¬ 
tions;  see  guideline  “VNA04-J.  Ensure  that  calls  to  chained  methods  are  atomic”  on  page  29 
for  more  information. 

•  passing  this  as  an  argument  to  an  alien  method  invoked  from  the  constructor  of  a  class 
whose  object  is  being  constructed 

•  using  inner  classes.  An  inner  class  implicitly  holds  a  reference  to  the  instance  of  its  outer 
class,  unless  the  inner  class  is  declared  static. 

•  publishing  by  assigning  thi  s  to  a  public  static  variable  from  the  constructor  of  a  class  whose 
object  is  being  constructed 

•  overriding  the  fmalizer  of  a  non-final  class  and  obtaining  the  this  reference  of  a  partially 
initialized  instance,  when  the  construction  of  the  object  ceases.  (For  more  information,  see 
guideline  “OBJ04-J.  Do  not  allow  partially  initialized  objects  to  be  accessed.”10)  This  can 
happen  when  the  constructor  throws  an  exception.  Misuse  is  not  limited  to  untrusted  code; 
trusted  code  can  also  inadvertently  add  a  finalizer  and  let  this  escape  by  violating  guideline 
“OBJ08-J.  Avoid  using  finalizers.”10 

•  passing  internal  object  state  to  an  alien  method.  This  enables  the  method  to  retrieve  the  this 
reference  of  the  internal  member  object. 

This  guideline  describes  the  potential  consequences  of  allowing  the  this  reference  to  escape  dur¬ 
ing  object  construction,  including  race  conditions  and  improper  initialization.  For  example,  dec¬ 
laring  a  field  final  ensures  that  all  threads  see  it  in  a  fully  initialized  state  only  when  the  this 
reference  does  not  escape  during  the  corresponding  object’s  construction.  Guideline  “TSM03-J. 
Do  not  publish  partially  initialized  objects”  on  page  162  describes  the  guarantees  provided  by  var¬ 
ious  mechanisms  for  safe  publication  and  relies  on  conformance  to  this  guideline.  In  general,  it  is 
important  to  detect  cases  where  the  this  reference  can  leak  out  beyond  the  scope  of  the  current 
context.  In  particular,  public  variables  and  methods  should  be  carefully  scrutinized. 


10  This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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6.2.1  Noncompiiant  Code  Example  (Publish  Before  Initialization) 

This  noncompiiant  code  example  publishes  the  this  reference  before  initialization  has  con¬ 
cluded,  by  storing  it  in  a  public  static  volatile  class  field. 

final  class  Publisher  { 

public  static  volatile  Publisher  published; 
int  num; 

Publisher (int  number)  { 
published  =  this; 

//  Initialization 
this. num  =  number; 

//  ... 

} 

} 

Consequently,  other  threads  may  obtain  a  partially  initialized  Publisher  instance.  Also,  if  the 
object  initialization  (and  consequently,  its  construction)  depends  on  a  security  check  within  the 
constructor,  the  security  check  can  be  bypassed  if  an  untrusted  caller  obtains  the  partially  initia¬ 
lized  instance.  (For  more  information,  see  guideline  “OBJ04-J.  Do  not  allow  partially  initialized 
objects  to  be  accessed.”11) 

6.2.2  Noncompiiant  Code  Example  (Non-Volatile  Public  Static  Field) 

This  noncompiiant  code  example  publishes  the  this  reference  in  the  last  statement  of  the  con¬ 
structor  but  is  still  vulnerable  because  the  published  field  is  not  declared  volatile  and  has  pub¬ 
lic  accessibility. 

final  class  Publisher  { 

public  static  Publisher  published; 
int  num; 

Publisher (int  number)  { 

//  Initialization 
this. num  =  number; 

//  ... 

published  =  this; 

} 

} 

Because  the  field  is  non-volatile  and  non-final,  the  statements  within  the  constructor  can  be  reor¬ 
dered  by  the  compiler  in  such  a  way  that  the  this  reference  is  published  before  the  initialization 
statements  have  executed. 


11  This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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6.2.3  Compliant  Solution  (Volatile  Field  and  Publish  After  Initialization) 

This  compliant  solution  declares  the  published  field  volatile  and  reduces  its  accessibility  to 
package-private  so  that  callers  outside  the  current  package  scope  cannot  obtain  the  this  refer¬ 
ence. 

final  class  Publisher  { 

static  volatile  Publisher  published; 
int  num; 

Publisher (int  number)  { 

//  Initialization 
this. num  =  number; 

//  ... 

published  =  this; 

} 

} 

The  constructor  publishes  the  this  reference  after  initialization  has  concluded.  However,  the 
caller  that  instantiates  Publisher  must  ensure  that  it  does  not  see  the  default  value  of  the  num 
field  before  it  is  initialized  (a  violation  of  guideline  “TSM03-J.  Do  not  publish  partially  initialized 
objects”  on  page  162).  Consequently,  the  field  that  holds  the  reference  to  Publisher  might  need 
to  be  declared  volatile  in  the  caller. 

Initialization  statements  may  be  reordered  if  the  published  field  is  not  declared  volatile.  The 
Java  compiler,  however,  does  not  allow  fields  to  be  declared  both  volatile  and  final. 

The  class  Publisher  must  also  be  final;  otherwise,  a  subclass  can  call  its  constructor  and  pub¬ 
lish  the  this  reference  before  the  subclass’s  initialization  has  concluded. 

6.2.4  Compliant  Solution  (Public  Static  Factory  Method) 

This  compliant  solution  eliminates  the  internal  member  field  and  provides  a  newlnstance  ( ) 
factory  method  that  creates  and  returns  a  Publisher  instance. 

final  class  Publisher  { 
final  int  num; 

private  Publisher (int  number)  { 

//  Initialization 
this. num  =  number; 

} 

public  static  Publisher  newlnstance (int  number)  { 

Publisher  published  =  new  Publisher (number ) ; 
return  published; 

} 

} 
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This  approach  ensures  that  threads  do  not  see  an  inconsistent  Publisher  instance.  The  num  field 
is  also  declared  final,  making  the  class  immutable  and  eliminating  the  possibility  of  obtaining  a 
partially  initialized  object. 

6.2.5  Noncompliant  Code  Example  (Handlers) 

This  noncompliant  code  example  defines  the  ExceptionReporter  interface: 

public  interface  ExceptionReporter  { 

public  void  setExceptionReporter (ExceptionReporter  er) ; 
public  void  report (Throwable  exception); 

} 

This  interface  is  implemented  by  the  Def  aultExceptionReporter  class,  which  reports  ex¬ 
ceptions  after  filtering  out  any  sensitive  information.  (For  more  information,  see  guideline 
“EXC01-J.  Use  a  class  dedicated  to  reporting  exceptions.”12) 

The  Def  aultExceptionReporter  constructor  prematurely  publishes  the  this  reference  be¬ 
fore  construction  of  the  object  has  concluded.  This  occurs  in  the  last  statement  of  the  constructor 
(er .  setExceptionReporter  (this) ),  which  sets  the  exception  reporter.  Because  it  is  the 
last  statement  of  the  constructor,  this  may  be  misconstrued  as  benign. 

//  Class  DefaultExceptionReporter 

public  class  DefaultExceptionReporter  implements  ExceptionReporter  { 
public  DefaultExceptionReporter (ExceptionReporter  er)  { 

//  Carry  out  initialization 

//  Incorrectly  publishes  the  "this"  reference 
er . setExceptionReporter (this) ; 

} 

//  Implementation  of  setExceptionReporter ( )  and  report  () 

} 

The  MyExceptionReporter  class  subclasses  DefaultExceptionReporter  with  the  intent 
of  adding  a  logging  mechanism  that  logs  critical  messages  before  an  exception  is  reported. 

//  Class  MyExceptionReporter  derives  from  DefaultExceptionReporter 
public  class  MyExceptionReporter  extends  DefaultExceptionReporter  { 
private  final  Logger  logger; 

public  MyExceptionReporter (ExceptionReporter  er)  { 
super  (er);  //  Calls  superclass's  constructor 

logger  =  Logger .getLogger ("com. organization. Log") ;  //  Obtain  the  default  logger 

} 

public  void  report (Throwable  t)  { 

logger . log (Level . FINEST, "Loggable  exception  occurred",  t) ; 

} 

} 

12  This  guideline  is  described  at  https://www.securecoding.cert.org/confluence/display/java/. 
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Its  constructor  invokes  the  DefaultExceptionReporter  superclass’s  constructor  (a  manda¬ 
tory  first  step),  which  publishes  the  exception  reporter  before  the  initialization  of  the  subclass  has 
concluded.  Note  that  the  subclass  initialization  consists  of  obtaining  an  instance  of  the  default 
logger.  Publishing  the  exception  reporter  is  equivalent  to  setting  it  to  receive  and  handle  excep¬ 
tions  from  that  point  on. 

If  an  exception  occurs  before  the  call  to  Logger .  getLogger  ( )  in  the 

MyExceptionReporter  subclass,  it  is  not  logged.  Instead,  a  NullPointerException  is 
generated,  which  may,  itself,  be  consumed  by  the  reporting  mechanism  without  being  logged. 

This  erroneous  behavior  results  from  the  race  condition  between  an  oncoming  exception  and  the 
initialization  of  MyExceptionReporter.  If  the  exception  comes  too  soon,  it  finds 
MyExceptionReporter  in  an  inconsistent  state.  This  behavior  is  especially  counterintuitive 
because  logger  is  declared  final  and  is  not  expected  to  contain  an  uninitialized  value. 

This  problem  can  also  occur  when  an  event  listener  is  published  prematurely.  Consequently,  it 
starts  receiving  event  notifications  even  before  the  subclass’s  initialization  has  concluded. 

6.2.6  Compliant  Solution 

Instead  of  publishing  the  this  reference  from  the  DefaultExceptionReporter  constructor, 
this  compliant  solution  adds  the  publishExceptionReporter  ( )  method  to 
DefaultExceptionReporter  to  set  the  exception  reporter.  This  method  can  be  invoked  on  a 
subclass  instance,  after  the  subclass’s  initialization  has  concluded. 

public  class  DefaultExceptionReporter  implements  ExceptionReporter  { 
public  DefaultExceptionReporter (ExceptionReporter  er)  { 

II  ... 

} 

//  Should  be  called  after  subclass's  initialization  is  over 
public  void  publishExceptionReporter ( )  { 

setExceptionReporter (this) ;  //  Registers  this  exception  reporter 

} 

//  Implementation  of  setExceptionReporter))  and  report!) 

} 

The  MyExceptionReporter  subclass  inherits  the  publishExceptionReporter  ( )  me¬ 
thod,  and  a  caller  who  instantiates  MyExceptionReporter  can  use  its  instance  to  set  the  ex¬ 
ception  reporter,  after  initialization  is  over. 

//  Class  MyExceptionReporter  derives  from  DefaultExceptionReporter 
public  class  MyExceptionReporter  extends  DefaultExceptionReporter  { 
private  final  Logger  logger; 

public  MyExceptionReporter (ExceptionReporter  er)  { 
super (er) ;  //  Calls  superclass's  constructor 
logger  =  Logger . getLogger ( "com. organization . Log" ) ; 
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} 

//  Implementations  of  publishExceptionReporter ( ) ,  setExceptionReporter ( )  and 
//  report!)  are  inherited 

} 

This  approach  ensures  that  the  reporter  cannot  be  set  before  the  constructor  has  fully  initialized 
the  subclass  and  enabled  logging. 

6.2.7  Noncompliant  Code  Example  (Inner  Class) 

Inner  classes  maintain  a  copy  of  the  this  reference  of  the  outer  object.  Consequently,  the  this 
reference  may  leak  outside  the  scope  [Goetz  2002].  This  noncompliant  code  example  uses  a  dif¬ 
ferent  implementation  of  the  Def  aultExceptionReporter  class.  The  constructor  uses  an 
anonymous  inner  class  to  publish  a  filter  ( )  method. 

public  class  DefaultExceptionReporter  implements  ExceptionReporter  { 
public  Def aultExceptionReporter (ExceptionReporter  er)  { 

er . setExceptionReporter (new  DefaultExceptionReporter (er)  { 
public  void  report (Throwable  t)  { 
filter  (t) ; 

} 

})  ; 

} 

//  Default  implementations  of  setExceptionReporter ( )  and  report!) 

} 

The  this  reference  of  the  outer  class  is  published  by  the  inner  class  so  that  other  threads  can  see 
it.  Furthermore,  if  the  class  is  subclassed,  the  issue  described  in  the  noncompliant  code  example 
for  handlers  resurfaces. 

6.2.8  Compliant  Solution 

A  private  constructor  alongside  a  public  static  factory  method  can  safely  publish  the 
filter  ( )  method  from  within  the  constructor  [Goetz  2006]. 

public  class  DefaultExceptionReporter  implements  ExceptionReporter  { 
private  final  DefaultExceptionReporter  defaultER; 

private  Def aultExceptionReporter (ExceptionReporter  excr)  { 
defaultER  =  new  Def aultExceptionReporter (excr )  { 

public  void  report (Throwable  t)  { 
filter  (t) ; 

} 

}  ; 

} 

public  static  DefaultExceptionReporter  newlnstance (ExceptionReporter  excr)  { 
DefaultExceptionReporter  der  =  new  DefaultExceptionReporter (excr) ; 
excr . setExceptionReporter (der . defaultER) ; 
return  der; 
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} 

//  Default  implementations  of  setExceptionReporter ( )  and  report () 


Because  the  constructor  is  private,  untrusted  code  cannot  create  instances  of  the  class,  prohibiting 
the  this  reference  from  escaping.  Using  a  public  static  factory  method  to  create  new  instances 
also  protects  against  publication  of  partially  initialized  objects  (see  guideline  “TSM03-J.  Do  not 
publish  partially  initialized  objects”  on  page  162)  and  untrusted  manipulation  of  internal  object 
state. 

6.2.9  Noncompliant  Code  Example  (Thread) 

This  noncompliant  code  example  starts  a  thread  from  within  the  constructor. 

final  class  ThreadStarter  implements  Runnable  { 
public  ThreadStarter ( )  { 

Thread  thread  =  new  Thread (this) ; 
thread. start ( ) ; 

! 

@Override  public  void  run()  { 

II  ... 

i 

} 

The  new  thread  can  access  the  this  reference  of  the  current  object  [Goetz  2002,  Goetz  2006]. 
Notably,  the  Thread  ( )  constructor  is  alien  to  the  ThreadStarter  class. 

6.2.10  Compliant  Solution  (Thread) 

This  compliant  solution  creates  and  starts  the  thread  in  a  method  instead  of  the  constructor. 

final  class  ThreadStarter  implements  Runnable  { 
public  ThreadStarter ( )  { 

//  ... 

} 

public  void  startThread ( )  { 

Thread  thread  =  new  Thread (this) ; 
thread. start ( ) ; 

} 

@Override  public  void  run()  { 

//  ... 

1 

} 


CMU/SEI-2010-TR-015  |  155 


TSM01-J 


6.2.11  Exceptions 

TSM01-EX1:  It  is  safe  to  create  a  thread  in  the  constructor,  provided  the  thread  is  not  started  un¬ 
til  object  construction  has  completed.  This  is  because  a  call  to  start  ( )  on  a  thread  happens- 
before  any  actions  in  the  started  thread  [Gosling  2005]. 

In  this  code  example,  even  though  a  thread  referencing  this  is  created  in  the  constructor,  it  is  not 
started  until  its  start  ( )  method  is  called  from  the  startThread  ( )  method  [Goetz  2002, 
Goetz  2006]. 

final  class  ThreadStarter  implements  Runnable  { 

Thread  thread; 

public  ThreadStarter ( )  { 

thread  =  new  Thread (this) ; 

} 

public  void  startThread ( )  { 
thread. start ( ) ; 

1 

@Override  public  void  run()  { 

II  ... 
i 

} 

TSM01-EX2:  The  ObjectPreserver  pattern  [Grand  2002]  described  in  guideline  “TSM02-J. 
Do  not  use  background  threads  during  class  initialization”  on  page  157  is  also  a  safe  exception  to 
this  guideline. 

6.2.12  Risk  Assessment 


Allowing  the  this  reference  to  escape  may  result  in  improper  initialization  and  runtime  excep¬ 
tions. 


Guideline 
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TSM01-J 
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6.3  TSM02-J.  Do  not  use  background  threads  during  class  initialization 

Starting  and  using  background  threads  during  class  initialization  can  result  in  class  initialization 
cycles  and  deadlock.  For  example,  the  main  thread  responsible  for  performing  class  initialization 
can  block  waiting  for  the  background  thread,  which,  in  turn,  will  wait  for  the  main  thread  to  finish 
class  initialization.  This  issue  can  arise,  for  example,  when  a  database  connection  is  established  in 
a  background  thread  during  class  initialization  [Bloch  2005b]. 

6.3.1  Noncompliant  Code  Example  (Background  Thread) 

In  this  noncompliant  code  example,  the  static  initializer  starts  a  background  thread  as  part  of 
class  initialization.  The  background  thread  attempts  to  initialize  a  database  connection  but  needs 
to  wait  until  all  members  of  the  ConnectionFactory  class,  including  dbConnection,  have 
been  initialized. 

public  final  class  ConnectionFactory  { 
private  static  Connection  dbConnection; 

//  Other  fields  . . . 

static  { 

Thread  dblnitializerThread  =  new  Thread (new  Runnable ()  { 

@Override  public  void  run()  { 

//  Initialize  the  database  connection 
try  { 

dbConnection  =  DriverManager . getConnection ( "connection  string"); 

}  catch  (SQLException  e)  { 
dbConnection  =  null; 

I 

} 

})  ; 

//  Other  initialization,  for  example,  start  other  threads 

dblnitializerThread. start () ; 
try  { 

dblnitializerThread. joint); 

}  catch  ( Inter ruptedException  ie)  { 
throw  new  AssertionError  (ie) ; 

Jf 

public  static  Connection  getConnection ( )  { 

if  (dbConnection  ==  null)  { 

throw  new  IllegalStateException ( "Error  initializing  connection" ) ; 

} 

return  dbConnection; 

} 

public  static  void  main (String [ ]  args)  { 
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II  ... 

Connection  connection  =  getConnection () ; 

} 

} 

Statically  initialized  fields  are  guaranteed  to  be  fully  constructed  before  they  are  made  visible  to 
other  threads.  (See  guideline  “TSM03-J.  Do  not  publish  partially  initialized  objects”  on  page  162 
for  more  information.)  Consequently,  the  background  thread  must  wait  for  the  main  (or  fore¬ 
ground)  thread  to  finish  initialization  before  it  can  proceed.  However,  the  ConnectionFactory 
class’s  main  thread  invokes  the  j  oin  ( )  method,  which  waits  for  the  background  thread  to  finish. 
This  interdependency  causes  a  class  initialization  cycle  that  results  in  a  deadlock  situation  [Bloch 
2005b], 

Similarly,  it  is  inappropriate  to  start  threads  from  constructors.  (See  guideline  “TSM01-J.  Do  not 
let  the  “this”  reference  escape  during  object  construction”  on  page  149  for  more  information.) 
Creating  timers  that  perform  recurring  tasks  and  starting  those  timers  from  within  the  code  re¬ 
sponsible  for  initialization  introduces  liveness  issues. 

6.3.2  Compliant  Solution  (static  Initializer,  No  Background  Threads) 

This  compliant  solution  does  not  spawn  any  background  threads  from  the  static  initializer.  In¬ 
stead,  all  fields  are  initialized  in  the  main  thread. 

public  final  class  ConnectionFactory  { 
private  static  Connection  dbConnection; 

//  Other  fields  . . . 

static  { 

//  Initialize  a  database  connection 
try  { 

dbConnection  =  DriverManager . getConnection ( "connection  string") ; 

}  catch  (SQLException  e)  { 
dbConnection  =  null; 

i 

//  Other  initialization  (do  not  start  any  threads) 

1 

II  ... 

) 


CMU/SEI-2010-TR-015  |  158 


TSM02-J 


6.3.3  Compliant  Solution  (ThreadLocal) 

This  compliant  solution  initializes  the  database  connection  from  a  ThreadLocal  object  so  that 
every  thread  can  obtain  its  own  instance  of  the  connection. 

public  final  class  ConnectionFactory  { 

private  static  final  ThreadLocal<Connection>  connectionHolder 
=  new  ThreadLocal<Connection> ( )  { 

@Override  public  Connection  initialValue ( )  { 

try  { 

Connection  dbConnection  =  DriverManager . getConnection ( "connection  string"); 
return  dbConnection; 

}  catch  (SQLException  e)  { 
return  null; 


} ; 

//  Other  fields  . . . 

static  { 

//  Other  initialization  (do  not  start  any  threads) 

} 

public  static  Connection  getConnection ( )  { 

Connection  connection  =  connectionHolder . get () ; 
if  (connection  ==  null)  { 

throw  new  IllegalStateException ( "Error  initializing  connection"); 

} 

return  connection; 

} 

public  static  void  main (String [ ]  args)  { 

//  ... 

Connection  connection  =  getConnection () ; 

} 


The  static  initializer  can  be  used  to  initialize  any  other  shared  class  fields.  Alternatively,  the  fields 
can  be  initialized  from  the  initialValue  ( )  method. 
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6.3.4  Exceptions 

TSM02-EX1:  It  is  permissible  to  start  a  background  thread  during  class  initialization  provided  the 
thread  does  not  access  any  fields.  For  example,  the  Obj  ectPreserver  class  (based  on  Patterns 
in  Java  [Grand  2002])  shown  below  provides  a  mechanism  for  storing  object  references,  which 
prevents  an  object  from  being  garbage-collected,  even  if  the  object  is  not  de-referenced  in  the  fu¬ 
ture. 

public  final  class  Obj ectPreserver  implements  Runnable  { 

private  static  final  Obj ectPreserver  lifeLine  =  new  Ob j ectPreserver () ; 

private  Obj ectPreserver ()  { 

Thread  thread  =  new  Thread (this) ; 
thread. setDaemon (true) ; 

thread. start () ;  //  Keep  this  object  alive 

} 

//  Neither  this  class  nor  HashMap  will  be  garbage-collected. 

//  References  from  HashMap  to  other  objects  will  also  exhibit  this  property 
private  static  final  ConcurrentHashMap<Integer ,  Object>  protectedMap 
=  new  ConcurrentHashMap<Integer ,  Object>(); 

public  synchronized  void  run()  { 
try  { 
wait ( ) ; 

}  catch  ( Inter ruptedException  e)  { 

Thread. currentThread () . interrupt () ;  //  Reset  interrupted  status 

} 

} 

//  Objects  passed  to  this  method  will  be  preserved  until 
//  the  unpreserveObject ()  method  is  called 
public  static  void  preserveObject (Object  obj)  { 
protectedMap .put (0,  obj); 

} 

//  Returns  the  same  instance  every  time 
public  static  Object  getObjectO  { 
return  protectedMap . get (0 ) ; 

} 

//  Unprotect  the  objects  so  that  they  can  be  garbage-collected 
public  static  void  unpreserveObject  ()  { 

protectedMap . remove (0) ; 

} 
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This  is  a  singleton  class.  (See  guideline  “MSC16-J.  Address  the  shortcomings  of  the  Singleton 
design  pattern”13  for  more  information  on  how  to  defensively  code  singleton  classes.)  The  initiali¬ 
zation  involves  creating  a  background  thread  using  the  current  instance  of  the  class.  The  thread 
waits  indefinitely  by  invoking  Ob  j  ect .  wait  ( ) .  Consequently,  this  object  persists  for  the  re¬ 
mainder  of  the  JVM’s  lifetime.  Because  the  object  is  managed  by  a  daemon  thread,  the  thread 
does  not  hinder  a  normal  shutdown  of  the  JVM. 

While  the  initialization  does  involve  a  background  thread,  that  thread  does  not  access  any  fields  or 
create  any  liveness  or  safety  issues.  Consequently,  this  code  is  a  safe  and  useful  exception  to  this 
guideline. 

6.3.5  Risk  Assessment 


Starting  and  using  background  threads  during  class  initialization  can  result  in  deadlock  conditions. 
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6.4  TSM03-J.  Do  not  publish  partially  initialized  objects 

During  initialization  of  a  shared  object,  the  object  must  only  be  accessible  to  the  thread  construct¬ 
ing  it.  However,  the  object  can  be  published  safely  (that  is,  made  visible  to  other  threads)  once  it 
is  initialized.  The  JMM  allows  multiple  threads  to  observe  the  object  after  its  initialization  has 
begun,  but  before  it  has  concluded.  Consequently,  it  is  important  to  ensure  that  a  partially  initia¬ 
lized  object  is  not  published. 

This  guideline  prohibits  publishing  a  reference  to  a  partially  initialized  member  object  instance 
before  initialization  has  concluded.  Guideline  “TSM01-J.  Do  not  let  the  “this”  reference  escape 
during  object  construction”  on  page  149  prohibits  the  this  reference  of  the  current  object  from 
escaping. 

6.4.1  Noncompliant  Code  Example 

This  noncompliant  code  example  constructs  a  Helper  object  in  the  initialize  ( )  method  of 
the  Foo  class.  The  Helper  object’s  fields  are  initialized  by  its  constructor. 

class  Foo  { 

private  Helper  helper; 

public  Helper  getHelperf)  { 
return  helper; 

1 

public  void  initialize  ()  { 

helper  =  new  Helper  (42); 

| 

| 

public  class  Helper  { 
private  int  n; 

public  Helper (int  n)  { 
this.n  =  n; 

} 

II  ... 

} 

If  a  thread  accesses  helper  using  the  getHelper  ( )  method  before  the  initialize  ( )  me¬ 
thod  has  been  called,  the  thread  will  observe  an  uninitialized  helper  field.  Later,  if  one  thread 
calls  initialize  ( )  and  another  calls  getHelper  ( ) ,  the  second  thread  might  observe  one  of 
the  following: 

•  the  helper  reference  as  NULL 

•  a  fully  initialized  Helper  object  with  the  n  field  set  to  42 

•  a  partially  initialized  Helper  object  with  an  uninitialized  n  that  contains  the  default  value  0 
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In  particular,  the  JMM  permits  compilers  to  allocate  memory  for  the  new  Helper  object  and  as¬ 
sign  it  to  the  helper  field  before  initializing  it.  In  other  words,  the  compiler  can  reorder  the  write 
to  the  helper  instance  field  with  the  write  that  initializes  the  Helper  object  (that  is, 
this  .  n  =  n)  such  that  the  former  occurs  first.  This  exposes  a  race  window  during  which  other 
threads  may  observe  a  partially  initialized  Helper  object  instance. 

There  is  a  separate  issue:  if  two  threads  call  initialize  ( ) ,  two  Helper  objects  are  created. 
This  is  a  performance  issue  and  not  a  correctness  issue  because  n  will  be  properly  initialized  and 
the  unused  Helper  objects  will  be  garbage-collected. 

6.4.2  Compliant  Solution  (Synchronization) 

The  publication  of  partially  constructed  object  references  can  be  prevented  by  using  method  syn¬ 
chronization,  as  shown  in  this  compliant  solution. 

class  Foo  { 

private  Helper  helper; 

public  synchronized  Helper  getHelper()  { 
return  helper; 

} 

public  synchronized  void  initialize  ()  { 

helper  =  new  Helper  (42); 

} 


Synchronizing  both  methods  guarantees  that  they  will  not  execute  concurrently.  If  one  thread  calls 
initialize  ( )  just  before  another  thread  calls  getHelper  ( ) ,  the  synchronized 
initialize  ( )  method  will  always  finish  first.  The  synchronized  keyword  establishes  a 
happens-before  relationship  between  the  two  threads.  This  guarantees  that  the  thread  calling 
getHelper  ( )  sees  the  fully  initialized  Helper  object  or  none  at  all  (that  is,  helper  contains  a 
null  reference).  This  approach  guarantees  proper  publication  for  both  immutable  and  mutable 
members. 
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6.4.3  Compliant  Solution  (Final  Field) 

If  the  helper  field  is  declared  final,  it  is  guaranteed  to  be  fully  constructed  before  its  reference  is 
made  visible. 

class  Foo  { 

private  final  Helper  helper; 

public  Helper  getHelper()  { 
return  helper; 

| 

public  Foo  ()  { 

helper  =  new  Helper (42); 

} 


However,  this  solution  requires  the  assignment  of  a  new  Helper  instance  to  helper  from  Foo’s 
constructor.  According  to  the  Java  Language  Specification,  Section  17.5.2,  “Reading  Final  Fields 
During  Construction”  [Gosling  2005] 

A  read  of  a  final  field  of  an  object  within  the  thread  that  constructs  that  object  is  ordered 
with  respect  to  the  initialization  of  that  field  within  the  constructor  by  the  usual  happens- 
before  rules.  If  the  read  occurs  after  the  field  is  set  in  the  constructor,  it  sees  the  value  the 
final  field  is  assigned,  otherwise  it  sees  the  default  value. 

Consequently,  the  reference  to  the  Helper  instance  should  not  be  published  before  the  Foo 
class’s  constructor  has  finished  its  initialization  (see  guideline  “TSM01-J.  Do  not  let  the  “this” 
reference  escape  during  object  construction”  on  page  149). 

6.4.4  Compliant  Solution  (Final  Field  and  Thread-Safe  Composition) 

Some  collection  classes  provide  thread-safe  access  to  contained  elements.  If  the  Helper  object  is 
inserted  into  such  a  collection,  it  is  guaranteed  to  be  fully  initialized  before  its  reference  is  made 
visible.  This  compliant  solution  encapsulates  the  helper  field  in  a  Vector<Helper>. 

class  Foo  { 

private  final  Vector<Helper>  helper; 
public  Foo()  { 

helper  =  new  Vector<Helper> ( ) ; 

| 

public  Helper  getHelperf)  { 
if  (helper .  isEmpty  ()  )  { 
initialize ( ) ; 

} 

return  helper . elementAt (0 ) ; 

} 
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public  synchronized  void  initialize!)  { 
if  (helper .  isEmpty  ()  )  { 

helper . add (new  Helper (42)); 

} 

} 

The  helper  field  is  declared  final  to  guarantee  that  the  vector  is  created  before  any  accesses  take 
place.  It  can  be  initialized  safely  by  invoking  the  synchronized  initialize  ( )  method,  which 
ensures  that  only  one  Helper  object  is  ever  added  to  the  vector.  If  getHelper  ( )  is  invoked 
before  initialize  ( ) ,  it  calls  initialize  ( )  to  avoid  the  possibility  of  a  null-pointer  de¬ 
reference  by  the  client.  The  getHelper  ( )  method  does  not  require  synchronization  to  simply 
return  Helper,  and — because  the  synchronized  initialize  ( )  method  also  checks  to  make 
sure  helper  is  empty  before  adding  a  new  Helper  object — there  is  no  possibility  of  exploiting 
a  race  condition  to  add  a  second  object  to  the  vector. 

6.4.5  Compliant  Solution  (Static  Initialization) 

In  this  compliant  solution,  the  helper  field  is  statically  initialized,  ensuring  that  the  object  refe¬ 
renced  by  the  field  is  fully  initialized  before  its  reference  is  visible. 

//  Immutable  Foo 
final  class  Foo  { 

private  static  final  Helper  helper  =  new  Helper (42); 

public  static  Helper  getHelper ()  { 

return  helper; 

1 

} 


Although  not  a  requirement,  the  helper  field  should  be  declared  final  to  document  the  class’s 
immutability. 

According  to  the  Java  Memory  Model  and  Thread  Specification,  Section  9.2.3,  “Static  Final 
Fields”  [JSR-133  2004] 

The  rules  for  class  initialization  ensure  that  any  thread  that  reads  a  static  field  will  be 
synchronized  with  the  static  initialization  of  that  class,  which  is  the  only  place  where  stat¬ 
ic  final  fields  can  be  set.  Thus,  no  special  rules  in  the  JMM  are  needed  for  static 
final  fields. 
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6.4.6  Compliant  Solution  (Immutable  Object  -  Final  Fields,  Volatile  Reference) 

The  JMM  guarantees  that  any  final  fields  of  an  object  are  fully  initialized  before  a  published  ob¬ 
ject  becomes  visible  [Goetz  2006].  By  declaring  n  final,  the  Helper  class  is  made  immutable. 
Furthermore,  if  the  helper  field  is  declared  volatile  in  compliance  with  guideline  “VNA01-J. 
Ensure  visibility  of  shared  references  to  immutable  objects”  on  page  13,  Helper’s  reference  is 
guaranteed  to  be  made  visible  to  any  thread  that  calls  getHelper  ( )  after  Helper  has  been  fully 
initialized. 

class  Foo  { 

private  volatile  Helper  helper; 

public  Helper  getHelper  ()  { 

return  helper; 

} 

public  void  initialize ()  { 
helper  =  new  Helper  (42); 

} 

} 

//  Immutable  Helper 
public  final  class  Helper  { 
private  final  int  n; 

public  Helper (int  n)  { 
this.n  =  n; 

} 

II  ... 

} 

This  compliant  solution  requires  that  helper  be  declared  volatile  and  class  Helper  be  immuta¬ 
ble.  If  it  were  not  immutable,  the  code  would  violate  guideline  “VNA06-J.  Do  not  assume  that 
declaring  an  object  reference  volatile  guarantees  visibility  of  its  members”  on  page  35,  and  addi¬ 
tional  synchronization  would  be  necessary  (see  the  next  compliant  solution).  And  if  the 
helper  field  were  non-volatile,  it  would  violate  guideline  “VNA01-J.  Ensure  visibility  of  shared 
references  to  immutable  objects”  on  page  13. 

Similarly,  a  public  static  factory  method  that  returns  a  new  instance  of  Helper  can  be  provided 
in  the  Helper  class.  This  approach  allows  the  Helper  instance  to  be  created  in  a  private  con¬ 
structor. 

6.4.7  Compliant  Solution  (Mutable  Thread-Safe  Object,  Volatile  Reference) 

If  Helper  is  mutable  but  thread-safe,  it  can  be  published  safely  by  declaring  the  helper  field  in 
the  Foo  class  volatile. 

class  Foo  { 

private  volatile  Helper  helper; 
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public  Helper  getHelperO  { 
return  helper; 

I 

public  void  initialize  ()  { 
helper  =  new  Helper (42); 

} 

| 

//  Mutable  but  thread-safe  Helper 
public  class  Helper  { 
private  volatile  int  n; 

private  final  Object  lock  =  new  Object (); 

public  Helper (int  n)  { 
this.n  =  n; 

* 

public  void  setNfint  value)  { 
synchronized  (lock)  { 
n  =  value; 

I 

} 

} 

Because  the  Helper  object  can  change  state  after  its  construction,  synchronization  is  necessary  to 
ensure  the  visibility  of  mutable  members  after  initial  publication.  Consequently,  the  setN  ( )  me¬ 
thod  is  synchronized  to  provide  the  visibility  of  the  n  field  in  this  compliant  solution  (see  guide¬ 
line  “VNA06-J.  Do  not  assume  that  declaring  an  object  reference  volatile  guarantees  visibility  of 
its  members”  on  page  35). 

If  the  Helper  class  is  not  synchronized  properly,  declaring  helper  volatile  in  the  Foo  class 
only  guarantees  the  visibility  of  the  initial  publication  of  Helper  and  not  of  subsequent  state 
changes.  Consequently,  volatile  references  alone  are  inadequate  for  publishing  objects  that  are  not 
thread-safe. 

If  the  helper  field  in  the  Foo  class  is  not  declared  volatile,  the  n  field  should  be  declared  vola¬ 
tile  so  that  a  happens-before  relationship  is  established  between  the  initialization  of  n  and  the 
write  of  Helper  to  the  helper  field.  This  is  in  compliance  with  guideline  “VNA06-J.  Do  not 
assume  that  declaring  an  object  reference  volatile  guarantees  visibility  of  its  members”  on  page 
35.  This  is  required  only  when  the  caller  (class  Foo)  cannot  be  trusted  to  declare  helper  volatile. 

Because  the  Helper  class  is  declared  public,  it  uses  a  private  lock  to  handle  synchronization  in 
conformance  with  guideline  “LCKOO-J.  Use  private  final  lock  objects  to  synchronize  classes  that 
may  interact  with  untrusted  code”  on  page  41. 
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6.4.8  Exceptions 

TSM03-EX1:  Classes  that  prevent  partially  initialized  objects  from  being  used  may  publish  par¬ 
tially  initialized  objects.  This  may  be  implemented,  for  example,  by  setting  a  volatile  boolean  flag 
in  the  last  statement  of  the  initializing  code  and  ensuring  that  this  flag  is  set  before  allowing  class 
methods  to  execute. 


The  following  compliant  solution  illustrates  this  technique: 

public  class  Helper  { 
private  int  n; 

private  volatile  boolean  initialized;  //  Defaults  to  false 

public  Helper (int  n)  { 
this.n  =  n; 

this . initialized  =  true; 

I 

public  void  doSomething ( )  { 
if  (! initialized)  { 

throw  new  SecurityException ( "Cannot  use  partially  initialized  instance"); 

} 

II  ... 

} 

II  ... 

} 

This  technique  ensures  that  even  if  the  reference  to  the  Helper  object  instance  is  published  be¬ 
fore  its  initialization  is  over,  the  instance  is  unusable.  The  instance  is  unusable  because  every  me¬ 
thod  within  Helper  must  check  the  flag  to  determine  whether  the  initialization  has  finished. 

6.4.9  Risk  Assessment 


Failing  to  synchronize  access  to  shared  mutable  data  can  cause  different  threads  to  observe  differ¬ 
ent  states  of  the  object  or  a  partially  initialized  object. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

TSM03-J 

medium 

probable 

medium 

P8 

L2 
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6.5  TSM04-J.  Document  thread-safety  and  use  annotations  where  applicable 

The  Java  language  annotation  facility  is  useful  for  documenting  design  intent.  Source  code  anno¬ 
tation  is  a  mechanism  for  associating  metadata  with  a  program  element  and  making  it  available  to 
the  compiler,  analyzers,  debuggers,  or  the  JVM  for  examination.  Several  annotations  are  available 
for  documenting  thread-safety  or  the  lack  thereof. 

6.5.1  Obtaining  Concurrency  Annotations 

Two  sets  of  concurrency  annotations  are  freely  available  and  licensed  for  use  in  any  code.  The 
first  set  consists  of  four  annotations  described  in  Java  Concurrency  in  Practice  (JCIP)  [Goetz 
2006],  which  can  be  downloaded  atjcip.net  (jar,  javadoc,  source).  The  JCIP  annotations  are  re¬ 
leased  under  the  Creative  Commons  Attribution  License. 

The  second,  larger  set  of  concurrency  annotations  is  available  from  and  supported  by  SureLogic. 
These  annotations  are  released  under  The  Apache  Software  License,  Version  2.0  and  can  be 
downloaded  at  surelogic.com  (jar,  javadoc,  source).  They  can  be  verified  by  the  SureLogic  JSure 
tool  and  are  useful  for  documenting  code,  even  if  the  tool  is  unavailable.  These  annotations  in¬ 
clude  the  JCIP  annotations  because  they  are  supported  by  the  JSure  tool.  (JSure  also  supports  the 
use  of  the  JCIP  JAR  file.) 

To  use  the  annotations,  download  and  add  one  or  both  of  the  aforementioned  JAR  files  to  the 
code’s  build  path.  The  use  of  these  annotations  to  document  thread-safety  is  described  in  the  fol¬ 
lowing  sections. 

6.5.2  Documenting  Intended  Thread-Safety 

JCIP  provides  three  class-level  annotations  to  describe  the  programmer’s  design  intent  with  re¬ 
spect  to  thread-safety. 

The  @ThreadSafe  annotation  is  applied  to  a  class  to  indicate  that  it  is  thread-safe.  This  means 
that  no  sequences  of  accesses  (reads  and  writes  to  public  fields,  calls  to  public  methods)  can  leave 
the  object  in  an  inconsistent  state,  regardless  of  the  interleaving  of  these  accesses  by  the  runtime 
or  any  external  synchronization  or  coordination  on  the  part  of  the  caller. 

For  example,  the  Aircraft  class  shown  below  specifies  that  it  is  thread-safe  as  part  of  its  lock¬ 
ing  policy  documentation.  This  class  protects  the  x  and  y  fields  using  a  reentrant  lock. 

@ThreadSafe 

@Region ("private  AircraftState" ) 

@RegionLock ("StateLock  is  stateLock  protects  AircraftState") 
public  final  class  Aircraft  { 

private  final  Lock  stateLock  =  new  ReentrantLock ( ) ; 

//  ... 

@InRegion ("AircraftState") 
private  long  x,  y; 

II  ... 

public  void  setPosition (long  x,  long  y)  { 
stateLock . lock ( ) ; 
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try  { 

this.x  =  x; 
this.y  =  y; 

}  finally  { 

stateLock . unlock ( ) ; 

1 

} 

II  ... 

} 

The  @Region  and  @RegionLock  annotations  document  the  locking  policy  that  the  promise  of 
thread-safety  is  predicated  on. 

Even  if  one  or  more  @RegionLock  or  @GuardedBy  annotations  have  been  used  to  document 
the  locking  policy  of  a  class,  the  @ThreadSaf  e  annotation  provides  an  intuitive  way  for  review¬ 
ers  to  learn  that  the  class  is  thread-safe. 

The  @  Immutable  annotation  is  applied  to  immutable  classes.  Immutable  objects  are  inherently 
thread-safe;  after  they  are  fully  constructed,  they  may  be  published  via  a  volatile  reference  and 
shared  safely  among  multiple  threads. 

The  following  example  shows  an  immutable  Point  class: 

@ Immutable 

public  final  class  Point  { 
private  final  int  f_x; 
private  final  int  f_y; 

public  Point (int  x,  int  y)  { 
f_x  =  x ; 

f_y  =  y; 

} 

public  int  getX()  { 
return  f_x; 

} 

public  int  getY()  { 
return  f  y; 

| 

} 

According  to  Bloch  [Bloch  2008] 

It  is  not  necessary  to  document  the  immutability  of  enum  types.  Unless  it  is  obvious  from  the 
return  type,  static  factories  must  document  the  thread  safely  of  the  returned  object,  as  dem¬ 
onstrated  by  Collections . synchronizedMap. 

The  @NotThreadSaf  e  annotation  is  applied  to  classes  that  are  not  thread-safe.  Many  classes  fail 
to  document  whether  they  are  safe  for  multithreaded  use.  Consequently,  a  programmer  has  no 
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easy  way  to  determine  whether  the  class  is  thread-safe.  This  annotation  provides  a  clear  indication 
of  the  class’s  lack  of  thread-safety. 

For  example,  most  of  the  collection  implementations  provided  in  j  ava  .util  are  not  thread-safe. 
The  j  ava .  util .  ArrayList  class  could  document  this  as  follows: 

package  java. util .ArrayList; 

@NotThreadSafe 

public  class  ArrayList<E>  extends  ...  { 

II  ... 

} 

6.5.3  Documenting  Locking  Policies 

It  is  important  to  document  all  the  locks  that  are  being  used  to  protect  shared  state.  According  to 
Goetz  and  colleagues  [Goetz  2006] 

For  each  mutable  state  variable  that  may  be  accessed  by  more  than  one  thread,  all  accesses 
to  that  variable  must  be  performed  with  the  same  lock  held.  In  this  case,  we  say  that  the  va¬ 
riable  is  guarded  by  that  lock. 

JCIP  provides  the  @GuardedBy  annotation  for  this  purpose,  while  SureLogic  provides  the 
SRegionLock  annotation.  The  field  or  method  to  which  the  @GuardedBy  annotation  is  applied 
can  only  be  accessed  when  holding  a  particular  lock.  This  may  be  an  intrinsic  lock  or  a  dynamic 
lock  such  as  j  ava  .  util .  concurrent .  Lock. 

For  example,  the  following  MovablePoint  class  implements  a  movable  point  that  has  the  capa¬ 
bility  of  remembering  its  past  locations  using  the  memo  array  list. 

@ThreadSafe 

public  final  class  MovablePoint  { 

@GuardedBy ("this" ) 
double  xPos  =  1.0; 

@ Guar dedBy ("this") 
double  yPos  =  1.0; 

@ Guar dedBy ("itself" ) 

static  final  List<MovablePoint>  memo  =  new  ArrayList<MovablePoint> ( ) ; 

public  void  move (double  slope,  double  distance)  { 
synchronized  (this)  { 
rememberPoint (this) ; 
xPos  +=  (1  /  slope)  *  distance; 
yPos  +=  slope  *  distance; 


public  static  void  rememberPoint (MovablePoint  value)  { 
synchronized  (memo)  { 
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memo . add (value) ; 

} 

} 

} 

The  @GuardedBy  annotations  on  the  xPos  and  yPos  fields  indicate  that  access  to  these  fields  is 
protected  by  holding  a  lock  on  this  (as  is  done  in  the  move  ( )  method,  which  modifies  these 
fields).  The  @GuardedBy  annotation  on  the  memo  list  indicates  that  a  lock  on  the  ArrayList 
object  protects  its  contents  (as  is  done  in  the  rememberPoint  ( )  method). 

One  issue  with  the  @GuardedBy  annotation  is  that  it  does  not  clarify  that  there  is  a  relationship 
between  the  fields  of  a  class.  This  limitation  can  be  overcome  by  using  the  SureLogic 
@RegionLock  annotation,  which  declares  a  new  region  lock  for  the  class  to  which  this  annota¬ 
tion  is  applied.  This  declaration  creates  a  new  named  lock  that  associates  a  particular  lock  object 
with  a  region  of  the  class.  The  region  may  be  accessed  only  when  the  lock  is  held. 

For  example,  the  SimpleLock  locking  policy  indicates  that  synchronizing  on  the  instance  pro¬ 
tects  all  of  its  state: 

@RegionLock ( "SimpleLock  is  this  protects  Instance") 
class  Simple  {  ...  } 

Unlike  @GuardedBy,  the  SRegionLock  annotation  allows  the  programmer  to  give  an  explicit, 
and  hopefully  meaningful,  name  to  the  locking  policy. 

In  addition  to  naming  the  locking  policy,  the  @Region  annotation  allows  a  name  to  be  given  to 
the  region  of  the  state  that  is  being  protected.  That  name  makes  it  clear  that  the  state  and  locking 
policy  belong  together,  as  demonstrated  in  the  following  example: 

@Region ("private  AircraftPosition" ) 

@RegionLock ("StateLock  is  stateLock  protects  AircraftPosition") 
public  final  class  Aircraft  { 

private  final  Lock  stateLock  =  new  ReentrantLock ( ) ; 

@InRegion ("AircraftPosition") 
private  long  x,  y; 

@InRegion ("AircraftPosition") 
private  long  altitude; 

II  ... 

public  void  setPosition (long  x,  long  y)  { 
stateLock . lock ( ) ; 
try  { 

this.x  =  x; 
this.y  =  y; 

}  finally  { 

stateLock. unlock () ; 

} 

} 
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II  ... 

} 

In  this  example,  a  locking  policy  named  StateLock  is  used  to  indicate  that  locking  on 
stateLock  protects  the  named  AircraftPosition  region,  which  includes  the  mutable  state 
used  to  represent  the  position  of  the  aircraft. 

6.5.4  Construction  of  Mutable  Objects 

Typically,  object  construction  is  considered  an  exception  to  the  locking  policy  because  objects  are 
thread-confined  when  they  are  created.  An  object  is  confined  to  the  thread  that  uses  the  new  oper¬ 
ator  to  create  its  instance.  After  creation,  the  object  can  be  published  to  other  threads  safely.  How¬ 
ever,  the  object  is  not  shared  until  the  thread  that  created  the  instance  allows  it  to  be  shared.  Safe 
publication  approaches  discussed  in  guideline  “TSM01-J.  Do  not  let  the  “this”  reference  escape 
during  object  construction”  on  page  149  can  be  expressed  succinctly  with  the 
@Unique  ( "return"  )  annotation. 

For  example,  in  the  code  shown  below,  the  @Unique  ( "return" )  annotation  documents  that 
the  object  returned  from  the  constructor  is  a  unique  reference. 

@RegionLock ("Lock  is  this  protects  Instance") 
public  final  class  Example  { 
private  int  x  =  1; 
private  int  y; 

@Unique ("return") 
public  Example (int  y)  { 
this.y  =  y; 

} 

II  ... 

} 

6.5.5  Documenting  Thread-Confinement  Policies 

Sutherland  and  Scherlis  propose  annotations  that  can  document  thread-confinement  policies. 

Their  approach  allows  verification  of  the  annotations  against  code  as  it  exists  [Sutherland  2010], 

For  example,  the  following  annotations  express  the  design  intent  that  a  program  has,  at  most,  one 
AWT  event  dispatch  thread  and  several  Compute  threads,  and  that  the  Compute  threads  are  for¬ 
bidden  to  handle  AWT  data  structures  or  events: 

@ColorDeclare  AWT,  Compute 
SlncompatibleColors  AWT,  Compute 
SMaxColorCount  AWT  1 
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6.5.6  Documenting  Wait-Notify  Protocols 

According  to  Goetz  and  colleagues  [Goetz  2006] 

A  state-dependent  class  should  either  fully  expose  (and  document)  its  waiting  and  notifica¬ 
tion  protocols  to  subclasses,  or  prevent  subclasses  from  participating  in  them  at  all.  (This  is 
an  extension  of  “design  and  document  for  inheritance,  or  else  prohibit  it’’  [EJ  Item  15].)  At 
the  very  least,  designing  a  state-dependent  class  for  inheritance  requires  exposing  the  condi¬ 
tion  queues  and  locks  and  documenting  the  condition  predicates  and  synchronization  policy; 
it  may  also  require  exposing  the  underlying  state  variables.  (The  worst  thing  a  state- 
dependent  class  can  do  is  expose  its  state  to  subclasses  but  not  document  its  protocols  for 
waiting  and  notification;  this  is  like  a  class  exposing  its  state  variables  but  not  documenting 
its  invariants.). 

Wait-notify  protocols  should  be  documented  adequately.  Currently,  we  are  not  aware  of  any  anno¬ 
tations  for  this  purpose. 

6.5.7  Risk  Assessment 


Annotations  of  concurrent  code  document  the  design  intent  and  can  be  used  to  automate  the  detec¬ 
tion  and  prevention  of  race  conditions  and  data  races. 


Guideline 

Severity 

Likelihood 

Remediation  Cost 

Priority 

Level 

TSM04-  J 

low 

probable 

medium 

P4 

L3 
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alien  method 

“From  the  perspective  of  a  class  C,  an  alien  method  is  one  whose  behavior  is  not  fully  specified 
by  C.  This  includes  methods  in  other  classes  as  well  as  overrideable  methods  (neither  private  nor 
final)  in  C  itself’  [Goetz  2006], 

atomicity 

When  applied  to  an  operation  on  primitive  data,  indicates  that  other  threads  that  might  access  the 
data  might  see  the  data  as  it  exists  before  the  operation  occurs  or  after  the  operation  has  com¬ 
pleted,  but  may  never  see  an  intermediate  value  of  the  data. 

canonicalization 

Reducing  the  input  to  its  equivalent  simplest  known  form. 

class  variable 

A  class  variable  is  a  static  field  associated  with  the  containing  class. 

condition  predicate 

A  condition  predicate  is  an  expression  constructed  from  the  state  variables  of  a  class  that  must  be 
true  for  a  thread  to  continue  execution.  The  thread  pauses  execution,  via  Ob  j  ect .  wait  ( ) , 
Thread .  sleep  ( ) ,  or  some  other  mechanism,  and  is  resumed  later,  presumably  when  the  re¬ 
quirement  is  true  and  when  it  is  notified  [Goetz  2006]. 

conflicting  accesses 

Two  accesses  to  (reads  of  or  writes  to)  the  same  variable  provided  that  at  least  one  of  the  accesses 
is  a  write.  [Gosling  2005], 

data  race 

“Conflicting  accesses  of  the  same  variable  that  are  not  ordered  by  a  happens-before  relationship” 
[Gosling  2005]. 

deadlock 

Two  or  more  threads  are  said  to  have  deadlocked  when  both  block  waiting  for  each  others’  locks. 
Neither  thread  can  make  any  progress. 
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happens-before  order 

“Two  actions  can  be  ordered  by  a  happens-before  relationship.  If  one  action  happens-before 
another,  then  the  first  is  visible  to  and  ordered  before  the  second.  [.  .  .]  It  should  be  noted  that  the 
presence  of  a  happens-before  relationship  between  two  actions  does  not  necessarily  imply  that 
they  have  to  take  place  in  that  order  in  an  implementation.  If  the  reordering  produces  results  con¬ 
sistent  with  a  legal  execution,  it  is  not  illegal.  [.  .  .]  More  specifically,  if  two  actions  share  a  hap¬ 
pens-before  relationship,  they  do  not  necessarily  have  to  appear  to  have  happened  in  that  order  to 
any  code  with  which  they  do  not  share  a  happens-before  relationship.  Writes  in  one  thread  that  are 
in  a  data  race  with  reads  in  another  thread  may,  for  example,  appear  to  occur  out  of  order  to  those 
reads”  [Gosling  2005], 

heap  memory 

“Memory  that  can  be  shared  between  threads  is  called  shared  memory  or  heap  memory.  All  in¬ 
stance  fields,  static  fields  and  array  elements  are  stored  in  heap  memory. [...]  Local  variables 
(§14.4),  formal  method  parameters  (§8.4.1)  or  exception  handler  parameters  are  never  shared  be¬ 
tween  threads  and  are  unaffected  by  the  memory  model”  [Gosling  2005]. 

immutable 

When  applied  to  an  object,  this  means  that  its  state  cannot  be  changed  after  being  initialized. 

“An  object  is  immutable  if: 

•  Its  state  cannot  be  modified  after  construction; 

•  All  its  fields  are  final;  [12]  and 

•  It  is  properly  constructed  (the  this  reference  does  not  escape  during  construction). 

[12]  It  is  technically  possible  to  have  an  immutable  object  without  all  fields  being  final. 

String  is  such  a  class  but  this  relies  on  delicate  reasoning  about  benign  data  races  that  requires  a 
deep  understanding  of  the  Java  Memory  Model.  (For  the  curious:  String  lazily  computes  the 
hash  code  the  first  time  hashCode  is  called  and  caches  it  in  a  nonfinal  field,  but  this  works  only 
because  that  field  can  take  on  only  one  nondefault  value  that  is  the  same  every  time  it  is  computed 
because  it  is  derived  deterministically  from  immutable  state”  [Goetz  2006].  Immutable  objects  are 
inherently  thread-safe;  they  may  be  shared  between  multiple  threads  or  published  without  syn¬ 
chronization,  though  it  is  usually  required  to  declare  the  fields  containing  their  references  vola¬ 
tile  to  ensure  visibility.  An  immutable  object  may  contain  mutable  sub-objects,  provided  the 
state  of  the  sub-objects  cannot  be  modified  after  construction  of  the  immutable  object  has  con¬ 
cluded. 

initialization  safety 

“An  object  is  considered  to  be  completely  initialized  when  its  constructor  finishes.  A  thread  that 
can  only  see  a  reference  to  an  object  after  that  object  has  been  completely  initialized  is  guaranteed 
to  see  the  correctly  initialized  values  for  that  object’s  final  fields”  [Gosling  2005]. 

interruption  policy 

“An  interruption  policy  determines  how  a  thread  interprets  an  interruption  request  -  what  it  does 
(if  anything)  when  one  is  detected,  what  units  of  work  are  considered  atomic  with  respect  to  inter¬ 
ruption,  and  how  quickly  it  reacts  to  interruption”  [Goetz  2006]. 

instance  variable 

An  instance  variable  is  a  non-static  field  that  is  a  part  of  every  instance  of  the  class 
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liveness 

Every  operation  or  method  invocation  executes  to  completion  without  interruptions,  even  if  it 
goes  against  safety. 


memory  model 

“The  rules  that  determine  how  memory  accesses  are  ordered  and  when  they  are  guaranteed  to  be 
visible  are  known  as  the  memory  model  of  the  Java  programming  language”  [Arnold  2006].  “A 
memory  model  describes,  given  a  program  and  an  execution  trace  of  that  program,  whether  the 
execution  trace  is  a  legal  execution  of  the  program”  [Gosling  2005], 

normalization 

Lossy  conversion  of  the  data  to  its  simplest  known  (and  anticipated)  form.  “When  implementa¬ 
tions  keep  strings  in  a  normalized  form,  they  can  be  assured  that  equivalent  strings  have  a  unique 
binary  representation”  [Davis  2009]. 

normalization  (URI) 

Normalization  is  the  process  of  removing  unnecessary  “.”  and  segments  from  the  path  com¬ 
ponent  of  a  hierarchical  URI.  Each  “.”  segment  is  simply  removed.  A  segment  is  removed 
only  if  it  is  preceded  by  a  non-"..”  segment.  Normalization  has  no  effect  upon  opaque  URIs  [Sun 
2009b], 

obsolete  reference 

“An  obsolete  reference  is  simply  a  reference  that  will  never  be  dereferenced  again”  [Bloch  08]. 

open  call 

“An  alien  method  invoked  outside  of  a  synchronized  region  is  known  as  an  open  call”  [Lea  2000a 
Section  2.4. 1.3,  Bloch  2008]. 

partial  order 

An  order  defined  for  some,  but  not  necessarily  all,  pairs  of  items.  For  instance,  the  sets  {a,  b}  and 
{a,  c,  d}  are  subsets  of  {a,  b,  c,  d},  but  neither  is  a  subset  of  the  other.  So  “subset  of’  is  a  partial 
order  on  sets.  [Black  2004a] 

program  order 

The  order  that  inter-thread  actions  are  performed  by  a  thread  according  to  the  intra-thread  seman¬ 
tics  of  the  thread.  “Program  order  [can  be  described]  as  the  order  of  bytecodes  present  in  the  .class 
file,  as  they  would  execute  based  on  control  flow  values”  (David  Holmes,  JMM  Mailing  List). 

publishing  objects 

“Publishing  an  object  means  making  it  available  to  code  outside  of  its  current  scope,  such  as  by 
storing  a  reference  to  it  where  other  code  can  find  it,  returning  it  from  a  nonprivate  method,  or 
passing  it  to  a  method  in  another  class”  [Goetz  2006], 

race  condition 

“General  races  cause  nondeterministic  execution  and  are  failures  in  programs  intended  to  be  de¬ 
terministic”  [Netzer  1992].  “A  race  condition  occurs  when  the  correctness  of  a  computation  de¬ 
pends  on  the  relative  timing  or  interleaving  of  multiple  threads  by  the  runtime”  [Goetz  2006]. 
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relativization  (URI) 

’’[Relativization]  is  the  inverse  of  resolution.  For  example,  relativizing  the  URI 

http :  // j  ava  .  sun  .  com/  j  2se/ 1.3/ docs/ guide/ index .  html  against  the  base  URI 
http :  / /  j  ava  .  sun  .  com/  j  2se/l .  3  yields  the  relative  URI  docs/ guide/ index .  html” 

[Sun  2009b], 

safety 

Its  main  goal  is  to  ensure  that  all  objects  maintain  consistent  states  in  a  multithreaded  environment 
[Lea  2000a]. 

sanitization 

Sanitization  is  a  term  used  for  validating  input  and  transforming  it  to  a  representation  that  con¬ 
forms  to  the  input  requirements  of  a  complex  subsystem.  For  example,  a  database  may  require  all 
invalid  characters  to  be  escaped  or  eliminated  prior  to  their  storage.  Input  sanitization  refers  to  the 
elimination  of  unwanted  characters  from  the  input  by  means  of  removal,  replacement,  encoding  or 
escaping  the  characters. 

sequential  consistency 

“Sequential  consistency  is  a  very  strong  guarantee  that  is  made  about  visibility  and  ordering  in  an 
execution  of  a  program.  Within  a  sequentially  consistent  execution,  there  is  a  total  order  over  all 
individual  actions  (such  as  reads  and  writes)  which  is  consistent  with  the  order  of  the  program, 
and  each  individual  action  is  atomic  and  is  immediately  visible  to  every  thread.  [.  .  .]  If  a  program 
is  correctly  synchronized,  then  all  executions  of  the  program  will  appear  to  be  sequentially  consis¬ 
tent  (§17.4.3)”  [Gosling  2005].  Sequential  consistency  implies  there  will  be  no  compiler  optimiza¬ 
tions  in  the  statements  of  the  action.  Adopting  sequential  consistency  as  the  memory  model  and 
disallowing  other  primitives  can  be  overly  restrictive  because  under  this  condition,  the  compiler  is 
not  allowed  to  make  optimizations  and  reorder  code  [Gosling  2005], 

synchronization 

“The  lava  programming  language  provides  multiple  mechanisms  for  communicating  between 
threads.  The  most  basic  of  these  methods  is  synchronization,  which  is  implemented  using  moni¬ 
tors.  Each  object  in  Java  is  associated  with  a  monitor,  which  a  thread  can  lock  or  unlock.  Only  one 
thread  at  a  time  may  hold  a  lock  on  a  monitor.  Any  other  threads  attempting  to  lock  that  monitor 
are  blocked  until  they  can  obtain  a  lock  on  that  monitor”  [Gosling  2005]. 

starvation 

A  condition  wherein  one  or  more  threads  prevent  other  threads  from  accessing  a  shared  resource 
over  extended  periods  of  time.  For  instance,  a  thread  that  invokes  a  synchronized  method,  which 
performs  some  time-consuming  operation,  starves  other  threads. 

thread -safe 

An  object  is  thread-safe  if  it  can  be  shared  by  multiple  threads  without  the  possibility  of  any  data 
races.  “A  thread-safe  object  performs  synchronization  internally,  so  multiple  threads  can  freely 
access  it  through  its  public  interface  without  further  synchronization”  [Goetz  2006].  Immutable 
classes  are  thread-safe  by  definition.  Mutable  classes  may  also  be  thread-safe  if  they  are  properly 
synchronized. 
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total  order 

An  order  defined  for  all  pairs  of  items  of  a  set.  For  instance,  <=  (less  than  or  equal  to)  is  a  total 
order  on  integers,  that  is,  for  any  two  integers,  one  of  them  is  less  than  or  equal  to  the  other  [Black 
2004b], 

trusted  code 

Code  that  is  loaded  by  the  primordial  class  loader,  irrespective  of  whether  it  constitutes  the  Java 
API  or  not.  In  this  text,  this  meaning  is  extended  to  include  code  that  is  obtained  from  a  known 
entity  and  given  permissions  that  untrusted  code  lacks.  By  this  definition,  untrusted  and  trusted 
code  can  coexist  in  the  namespace  of  a  single  class  loader  (not  necessarily  the  primordial  class 
loader).  In  such  cases,  the  security  policy  must  make  this  distinction  clear  by  assigning  appropri¬ 
ate  privileges  to  trusted  code,  while  denying  the  same  from  untrusted  code. 

untrusted  code 

Code  of  unknown  origin  that  can  potentially  cause  some  harm  when  executed.  Untrusted  code 
may  not  always  be  malicious  but  this  is  usually  hard  to  determine  automatically.  Consequently, 
untrusted  code  should  be  mn  in  a  sandboxed  environment. 

volatile 

“A  write  to  a  volatile  field  (§8.3.1 .4)  happens-before  every  subsequent  read  of  that  field”  [Gosling 
2005],  “Operations  on  the  master  copies  of  volatile  variables  on  behalf  of  a  thread  are  performed 
by  the  main  memory  in  exactly  the  order  that  the  thread  requested”  [Sun  1999b].  Accesses  to  a 
volatile  variable  are  sequentially  consistent,  which  also  means  that  the  operations  are  exempt 
from  compiler  optimizations.  Declaring  a  variable  volatile  ensures  that  all  threads  see  the 
most  up-to-date  value  of  the  variable,  if  any  thread  modifies  it.  Volatile  guarantees  atomic  reads 
and  writes  of  primitive  values,  however,  it  does  not  guarantee  the  atomicity  of  composite  opera¬ 
tions  such  as  variable  incrementation  (read-modify-write  sequence). 

vulnerability 

“A  set  of  conditions  that  allows  an  attacker  to  violate  an  explicit  or  implicit  security  policy” 
[Seacord  2005]. 
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